diff --git a/.gitignore b/.gitignore index 841d25b3..d63133a3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,3 @@ -Gemfile.lock -travis-ci/accounts.json -pkg +Gemfile.lock +pkg +*.gem \ No newline at end of file diff --git a/Gemfile b/Gemfile index 14861be2..e13dcbbf 100644 --- a/Gemfile +++ b/Gemfile @@ -1,9 +1,9 @@ -# frozen_string_literal: true - -source 'https://rubygems.org' - -group :test do - gem 'rake' -end - -gemspec +# frozen_string_literal: true + +source 'https://rubygems.org' + +group :test do + gem 'rake' +end + +gemspec diff --git a/doc/apple-pay.md b/doc/apple-pay.md index 7a9b1772..8d91fc98 100644 --- a/doc/apple-pay.md +++ b/doc/apple-pay.md @@ -1,51 +1,51 @@ -# Apple Pay - -```ruby -apple_pay_api = client.apple_pay -``` - -## Class Name - -`ApplePayApi` - -## Register Domain - -Activates a domain for use with Web Apple Pay and Square. A validation -will be performed on this domain by Apple to ensure is it properly set up as -an Apple Pay enabled domain. - -This endpoint provides an easy way for platform developers to bulk activate -Web Apple Pay with Square for merchants using their platform. - -To learn more about Apple Pay on Web see the Apple Pay section in the -[Embedding the Square Payment Form](/payment-form/add-digital-wallets/apple-pay) guide. - -```ruby -def register_domain(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Register Domain Request Hash`](/doc/models/register-domain-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Register Domain Response Hash`](/doc/models/register-domain-response.md) - -### Example Usage - -```ruby -body = {} -body[:domain_name] = 'example.com' - -result = apple_pay_api.register_domain(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Apple Pay + +```ruby +apple_pay_api = client.apple_pay +``` + +## Class Name + +`ApplePayApi` + +## Register Domain + +Activates a domain for use with Web Apple Pay and Square. A validation +will be performed on this domain by Apple to ensure is it properly set up as +an Apple Pay enabled domain. + +This endpoint provides an easy way for platform developers to bulk activate +Web Apple Pay with Square for merchants using their platform. + +To learn more about Apple Pay on Web see the Apple Pay section in the +[Embedding the Square Payment Form](https://developer.squareup.com/docs/payment-form/add-digital-wallets/apple-pay) guide. + +```ruby +def register_domain(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Register Domain Request Hash`](/doc/models/register-domain-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Register Domain Response Hash`](/doc/models/register-domain-response.md) + +### Example Usage + +```ruby +body = {} +body[:domain_name] = 'example.com' + +result = apple_pay_api.register_domain(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/catalog.md b/doc/catalog.md index 3a23c4a5..dadacc48 100644 --- a/doc/catalog.md +++ b/doc/catalog.md @@ -1,505 +1,505 @@ -# Catalog - -```ruby -catalog_api = client.catalog -``` - -## Class Name - -`CatalogApi` - -## Methods - -* [Batch Delete Catalog Objects](/doc/catalog.md#batch-delete-catalog-objects) -* [Batch Retrieve Catalog Objects](/doc/catalog.md#batch-retrieve-catalog-objects) -* [Batch Upsert Catalog Objects](/doc/catalog.md#batch-upsert-catalog-objects) -* [Catalog Info](/doc/catalog.md#catalog-info) -* [List Catalog](/doc/catalog.md#list-catalog) -* [Upsert Catalog Object](/doc/catalog.md#upsert-catalog-object) -* [Delete Catalog Object](/doc/catalog.md#delete-catalog-object) -* [Retrieve Catalog Object](/doc/catalog.md#retrieve-catalog-object) -* [Search Catalog Objects](/doc/catalog.md#search-catalog-objects) -* [Update Item Modifier Lists](/doc/catalog.md#update-item-modifier-lists) -* [Update Item Taxes](/doc/catalog.md#update-item-taxes) - -## Batch Delete Catalog Objects - -Deletes a set of [CatalogItem](./models/catalog-item.md)s based on the -provided list of target IDs and returns a set of successfully deleted IDs in -the response. Deletion is a cascading event such that all children of the -targeted object are also deleted. For example, deleting a CatalogItem will -also delete all of its [CatalogItemVariation](./models/catalog-item-variation.md) -children. - -`BatchDeleteCatalogObjects` succeeds even if only a portion of the targeted -IDs can be deleted. The response will only include IDs that were -actually deleted. - -```ruby -def batch_delete_catalog_objects(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Batch Delete Catalog Objects Request Hash`](/doc/models/batch-delete-catalog-objects-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Batch Delete Catalog Objects Response Hash`](/doc/models/batch-delete-catalog-objects-response.md) - -### Example Usage - -```ruby -body = {} -body[:object_ids] = ['W62UWFY35CWMYGVWK6TWJDNI', 'AA27W3M2GGTF3H6AVPNB77CK'] - -result = catalog_api.batch_delete_catalog_objects(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Batch Retrieve Catalog Objects - -Returns a set of objects based on the provided ID. -Each [CatalogItem](./models/catalog-item.md) returned in the set includes all of its -child information including: all of its -[CatalogItemVariation](./models/catalog-item-variation.md) objects, references to -its [CatalogModifierList](./models/catalog-modifier-list.md) objects, and the ids of -any [CatalogTax](./models/catalog-tax.md) objects that apply to it. - -```ruby -def batch_retrieve_catalog_objects(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Batch Retrieve Catalog Objects Request Hash`](/doc/models/batch-retrieve-catalog-objects-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Batch Retrieve Catalog Objects Response Hash`](/doc/models/batch-retrieve-catalog-objects-response.md) - -### Example Usage - -```ruby -body = {} -body[:object_ids] = ['W62UWFY35CWMYGVWK6TWJDNI', 'AA27W3M2GGTF3H6AVPNB77CK'] -body[:include_related_objects] = true - -result = catalog_api.batch_retrieve_catalog_objects(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Batch Upsert Catalog Objects - -Creates or updates up to 10,000 target objects based on the provided -list of objects. The target objects are grouped into batches and each batch is -inserted/updated in an all-or-nothing manner. If an object within a batch is -malformed in some way, or violates a database constraint, the entire batch -containing that item will be disregarded. However, other batches in the same -request may still succeed. Each batch may contain up to 1,000 objects, and -batches will be processed in order as long as the total object count for the -request (items, variations, modifier lists, discounts, and taxes) is no more -than 10,000. - -```ruby -def batch_upsert_catalog_objects(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Batch Upsert Catalog Objects Request Hash`](/doc/models/batch-upsert-catalog-objects-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Batch Upsert Catalog Objects Response Hash`](/doc/models/batch-upsert-catalog-objects-response.md) - -### Example Usage - -```ruby -body = {} -body[:idempotency_key] = '789ff020-f723-43a9-b4b5-43b5dc1fa3dc' -body[:batches] = [] - - -body[:batches][0] = {} -body[:batches][0][:objects] = [] - - -body[:batches][0][:objects][0] = {} -body[:batches][0][:objects][0][:type] = 'ITEM' -body[:batches][0][:objects][0][:id] = '#Tea' -body[:batches][0][:objects][0][:present_at_all_locations] = true -body[:batches][0][:objects][0][:item_data] = {} -body[:batches][0][:objects][0][:item_data][:name] = 'Tea' -body[:batches][0][:objects][0][:item_data][:description] = 'Hot Leaf Juice' -body[:batches][0][:objects][0][:item_data][:category_id] = '#Beverages' -body[:batches][0][:objects][0][:item_data][:tax_ids] = ['#SalesTax'] -body[:batches][0][:objects][0][:item_data][:variations] = [] - - -body[:batches][0][:objects][0][:item_data][:variations][0] = {} -body[:batches][0][:objects][0][:item_data][:variations][0][:type] = 'ITEM_VARIATION' -body[:batches][0][:objects][0][:item_data][:variations][0][:id] = '#Tea_Mug' -body[:batches][0][:objects][0][:item_data][:variations][0][:present_at_all_locations] = true - - -body[:batches][0][:objects][1] = {} -body[:batches][0][:objects][1][:type] = 'ITEM' -body[:batches][0][:objects][1][:id] = '#Coffee' -body[:batches][0][:objects][1][:present_at_all_locations] = true -body[:batches][0][:objects][1][:item_data] = {} -body[:batches][0][:objects][1][:item_data][:name] = 'Coffee' -body[:batches][0][:objects][1][:item_data][:description] = 'Hot Bean Juice' -body[:batches][0][:objects][1][:item_data][:category_id] = '#Beverages' -body[:batches][0][:objects][1][:item_data][:tax_ids] = ['#SalesTax'] -body[:batches][0][:objects][1][:item_data][:variations] = [] - - -body[:batches][0][:objects][1][:item_data][:variations][0] = {} -body[:batches][0][:objects][1][:item_data][:variations][0][:type] = 'ITEM_VARIATION' -body[:batches][0][:objects][1][:item_data][:variations][0][:id] = '#Coffee_Regular' -body[:batches][0][:objects][1][:item_data][:variations][0][:present_at_all_locations] = true - -body[:batches][0][:objects][1][:item_data][:variations][1] = {} -body[:batches][0][:objects][1][:item_data][:variations][1][:type] = 'ITEM_VARIATION' -body[:batches][0][:objects][1][:item_data][:variations][1][:id] = '#Coffee_Large' -body[:batches][0][:objects][1][:item_data][:variations][1][:present_at_all_locations] = true - - -body[:batches][0][:objects][2] = {} -body[:batches][0][:objects][2][:type] = 'CATEGORY' -body[:batches][0][:objects][2][:id] = '#Beverages' -body[:batches][0][:objects][2][:present_at_all_locations] = true - -body[:batches][0][:objects][3] = {} -body[:batches][0][:objects][3][:type] = 'TAX' -body[:batches][0][:objects][3][:id] = '#SalesTax' -body[:batches][0][:objects][3][:present_at_all_locations] = true - - - -result = catalog_api.batch_upsert_catalog_objects(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Catalog Info - -Returns information about the Square Catalog API, such as batch size -limits for `BatchUpsertCatalogObjects`. - -```ruby -def catalog_info -``` - -### Response Type - -[`Catalog Info Response Hash`](/doc/models/catalog-info-response.md) - -### Example Usage - -```ruby -result = catalog_api.catalog_info() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Catalog - -Returns a list of [CatalogObject](./models/catalog-object.md)s that includes -all objects of a set of desired types (for example, all [CatalogItem](./models/catalog-item.md) -and [CatalogTax](./models/catalog-tax.md) objects) in the catalog. The `types` parameter -is specified as a comma-separated list of valid [CatalogObject](./models/catalog-object.md) types: -`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`. - -__Important:__ ListCatalog does not return deleted catalog items. To retrieve -deleted catalog items, use SearchCatalogObjects and set `include_deleted_objects` -to `true`. - -```ruby -def list_catalog(cursor: nil, - types: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `cursor` | `String` | Query, Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
See [Pagination](/basics/api101/pagination) for more information. | -| `types` | `String` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve, for example
`ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.

The legal values are taken from the [CatalogObjectType](./models/catalog-object-type.md)
enumeration, namely `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, or `IMAGE`. | - -### Response Type - -[`List Catalog Response Hash`](/doc/models/list-catalog-response.md) - -### Example Usage - -```ruby -result = catalog_api.list_catalog() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Upsert Catalog Object - -Creates or updates the target [CatalogObject](./models/catalog-object.md). - -```ruby -def upsert_catalog_object(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Upsert Catalog Object Request Hash`](/doc/models/upsert-catalog-object-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Upsert Catalog Object Response Hash`](/doc/models/upsert-catalog-object-response.md) - -### Example Usage - -```ruby -body = {} -body[:idempotency_key] = 'af3d1afc-7212-4300-b463-0bfc5314a5ae' -body[:object] = {} -body[:object][:type] = 'ITEM' -body[:object][:id] = '#Cocoa' -body[:object][:item_data] = {} -body[:object][:item_data][:name] = 'Cocoa' -body[:object][:item_data][:description] = 'Hot chocolate' -body[:object][:item_data][:abbreviation] = 'Ch' - -result = catalog_api.upsert_catalog_object(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Catalog Object - -Deletes a single [CatalogObject](./models/catalog-object.md) based on the -provided ID and returns the set of successfully deleted IDs in the response. -Deletion is a cascading event such that all children of the targeted object -are also deleted. For example, deleting a [CatalogItem](./models/catalog-item.md) -will also delete all of its -[CatalogItemVariation](./models/catalog-item-variation.md) children. - -```ruby -def delete_catalog_object(object_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `object_id` | `String` | Template, Required | The ID of the [CatalogObject](./models/catalog-object.md) to be deleted. When an object is deleted, other
objects in the graph that depend on that object will be deleted as well (for example, deleting a
[CatalogItem](./models/catalog-item.md) will delete its [CatalogItemVariation](./models/catalog-item-variation.md)s). | - -### Response Type - -[`Delete Catalog Object Response Hash`](/doc/models/delete-catalog-object-response.md) - -### Example Usage - -```ruby -object_id = 'object_id8' - -result = catalog_api.delete_catalog_object(object_id: object_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Catalog Object - -Returns a single [CatalogItem](./models/catalog-item.md) as a -[CatalogObject](./models/catalog-object.md) based on the provided ID. The returned -object includes all of the relevant [CatalogItem](./models/catalog-item.md) -information including: [CatalogItemVariation](./models/catalog-item-variation.md) -children, references to its -[CatalogModifierList](./models/catalog-modifier-list.md) objects, and the ids of -any [CatalogTax](./models/catalog-tax.md) objects that apply to it. - -```ruby -def retrieve_catalog_object(object_id:, - include_related_objects: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `object_id` | `String` | Template, Required | The object ID of any type of [CatalogObject](./models/catalog-object.md)s to be retrieved. | -| `include_related_objects` | `Boolean` | Query, Optional | If `true`, the response will include additional objects that are related to the
requested object, as follows:

If the `object` field of the response contains a [CatalogItem](./models/catalog-item.md),
its associated [CatalogCategory](./models/catalog-category.md), [CatalogTax](./models/catalog-tax.md)es,
[CatalogImage](./models/catalog-image.md)s and [CatalogModifierList](./models/catalog-modifier-list.md)s
will be returned in the `related_objects` field of the response. If the `object`
field of the response contains a [CatalogItemVariation](./models/catalog-item-variation.md),
its parent [CatalogItem](./models/catalog-item.md) will be returned in the `related_objects` field of
the response.

Default value: `false` | - -### Response Type - -[`Retrieve Catalog Object Response Hash`](/doc/models/retrieve-catalog-object-response.md) - -### Example Usage - -```ruby -object_id = 'object_id8' - -result = catalog_api.retrieve_catalog_object(object_id: object_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Search Catalog Objects - -Queries the targeted catalog using a variety of query types: -[CatalogQuerySortedAttribute](./models/catalog-query-sorted-attribute.md), -[CatalogQueryExact](./models/catalog-query-exact.md), -[CatalogQueryRange](./models/catalog-query-range.md), -[CatalogQueryText](./models/catalog-query-text.md), -[CatalogQueryItemsForTax](./models/catalog-query-items-for-tax.md), and -[CatalogQueryItemsForModifierList](./models/catalog-query-items-for-modifier-list.md). - -```ruby -def search_catalog_objects(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Search Catalog Objects Request Hash`](/doc/models/search-catalog-objects-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Search Catalog Objects Response Hash`](/doc/models/search-catalog-objects-response.md) - -### Example Usage - -```ruby -body = {} -body[:object_types] = ['ITEM'] -body[:query] = {} -body[:query][:prefix_query] = {} -body[:query][:prefix_query][:attribute_name] = 'name' -body[:query][:prefix_query][:attribute_prefix] = 'tea' -body[:limit] = 100 - -result = catalog_api.search_catalog_objects(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Item Modifier Lists - -Updates the [CatalogModifierList](./models/catalog-modifier-list.md) objects -that apply to the targeted [CatalogItem](./models/catalog-item.md) without having -to perform an upsert on the entire item. - -```ruby -def update_item_modifier_lists(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Update Item Modifier Lists Request Hash`](/doc/models/update-item-modifier-lists-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Update Item Modifier Lists Response Hash`](/doc/models/update-item-modifier-lists-response.md) - -### Example Usage - -```ruby -body = {} -body[:item_ids] = ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'] -body[:modifier_lists_to_enable] = ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'] -body[:modifier_lists_to_disable] = ['7WRC16CJZDVLSNDQ35PP6YAD'] - -result = catalog_api.update_item_modifier_lists(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Item Taxes - -Updates the [CatalogTax](./models/catalog-tax.md) objects that apply to the -targeted [CatalogItem](./models/catalog-item.md) without having to perform an -upsert on the entire item. - -```ruby -def update_item_taxes(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Update Item Taxes Request Hash`](/doc/models/update-item-taxes-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Update Item Taxes Response Hash`](/doc/models/update-item-taxes-response.md) - -### Example Usage - -```ruby -body = {} -body[:item_ids] = ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'] -body[:taxes_to_enable] = ['4WRCNHCJZDVLSNDQ35PP6YAD'] -body[:taxes_to_disable] = ['AQCEGCEBBQONINDOHRGZISEX'] - -result = catalog_api.update_item_taxes(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Catalog + +```ruby +catalog_api = client.catalog +``` + +## Class Name + +`CatalogApi` + +## Methods + +* [Batch Delete Catalog Objects](/doc/catalog.md#batch-delete-catalog-objects) +* [Batch Retrieve Catalog Objects](/doc/catalog.md#batch-retrieve-catalog-objects) +* [Batch Upsert Catalog Objects](/doc/catalog.md#batch-upsert-catalog-objects) +* [Catalog Info](/doc/catalog.md#catalog-info) +* [List Catalog](/doc/catalog.md#list-catalog) +* [Upsert Catalog Object](/doc/catalog.md#upsert-catalog-object) +* [Delete Catalog Object](/doc/catalog.md#delete-catalog-object) +* [Retrieve Catalog Object](/doc/catalog.md#retrieve-catalog-object) +* [Search Catalog Objects](/doc/catalog.md#search-catalog-objects) +* [Update Item Modifier Lists](/doc/catalog.md#update-item-modifier-lists) +* [Update Item Taxes](/doc/catalog.md#update-item-taxes) + +## Batch Delete Catalog Objects + +Deletes a set of [CatalogItem](#type-catalogitem)s based on the +provided list of target IDs and returns a set of successfully deleted IDs in +the response. Deletion is a cascading event such that all children of the +targeted object are also deleted. For example, deleting a CatalogItem will +also delete all of its [CatalogItemVariation](#type-catalogitemvariation) +children. + +`BatchDeleteCatalogObjects` succeeds even if only a portion of the targeted +IDs can be deleted. The response will only include IDs that were +actually deleted. + +```ruby +def batch_delete_catalog_objects(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Batch Delete Catalog Objects Request Hash`](/doc/models/batch-delete-catalog-objects-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Batch Delete Catalog Objects Response Hash`](/doc/models/batch-delete-catalog-objects-response.md) + +### Example Usage + +```ruby +body = {} +body[:object_ids] = ['W62UWFY35CWMYGVWK6TWJDNI', 'AA27W3M2GGTF3H6AVPNB77CK'] + +result = catalog_api.batch_delete_catalog_objects(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Batch Retrieve Catalog Objects + +Returns a set of objects based on the provided ID. +Each [CatalogItem](#type-catalogitem) returned in the set includes all of its +child information including: all of its +[CatalogItemVariation](#type-catalogitemvariation) objects, references to +its [CatalogModifierList](#type-catalogmodifierlist) objects, and the ids of +any [CatalogTax](#type-catalogtax) objects that apply to it. + +```ruby +def batch_retrieve_catalog_objects(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Batch Retrieve Catalog Objects Request Hash`](/doc/models/batch-retrieve-catalog-objects-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Batch Retrieve Catalog Objects Response Hash`](/doc/models/batch-retrieve-catalog-objects-response.md) + +### Example Usage + +```ruby +body = {} +body[:object_ids] = ['W62UWFY35CWMYGVWK6TWJDNI', 'AA27W3M2GGTF3H6AVPNB77CK'] +body[:include_related_objects] = true + +result = catalog_api.batch_retrieve_catalog_objects(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Batch Upsert Catalog Objects + +Creates or updates up to 10,000 target objects based on the provided +list of objects. The target objects are grouped into batches and each batch is +inserted/updated in an all-or-nothing manner. If an object within a batch is +malformed in some way, or violates a database constraint, the entire batch +containing that item will be disregarded. However, other batches in the same +request may still succeed. Each batch may contain up to 1,000 objects, and +batches will be processed in order as long as the total object count for the +request (items, variations, modifier lists, discounts, and taxes) is no more +than 10,000. + +```ruby +def batch_upsert_catalog_objects(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Batch Upsert Catalog Objects Request Hash`](/doc/models/batch-upsert-catalog-objects-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Batch Upsert Catalog Objects Response Hash`](/doc/models/batch-upsert-catalog-objects-response.md) + +### Example Usage + +```ruby +body = {} +body[:idempotency_key] = '789ff020-f723-43a9-b4b5-43b5dc1fa3dc' +body[:batches] = [] + + +body[:batches][0] = {} +body[:batches][0][:objects] = [] + + +body[:batches][0][:objects][0] = {} +body[:batches][0][:objects][0][:type] = 'ITEM' +body[:batches][0][:objects][0][:id] = '#Tea' +body[:batches][0][:objects][0][:present_at_all_locations] = true +body[:batches][0][:objects][0][:item_data] = {} +body[:batches][0][:objects][0][:item_data][:name] = 'Tea' +body[:batches][0][:objects][0][:item_data][:description] = 'Hot Leaf Juice' +body[:batches][0][:objects][0][:item_data][:category_id] = '#Beverages' +body[:batches][0][:objects][0][:item_data][:tax_ids] = ['#SalesTax'] +body[:batches][0][:objects][0][:item_data][:variations] = [] + + +body[:batches][0][:objects][0][:item_data][:variations][0] = {} +body[:batches][0][:objects][0][:item_data][:variations][0][:type] = 'ITEM_VARIATION' +body[:batches][0][:objects][0][:item_data][:variations][0][:id] = '#Tea_Mug' +body[:batches][0][:objects][0][:item_data][:variations][0][:present_at_all_locations] = true + + +body[:batches][0][:objects][1] = {} +body[:batches][0][:objects][1][:type] = 'ITEM' +body[:batches][0][:objects][1][:id] = '#Coffee' +body[:batches][0][:objects][1][:present_at_all_locations] = true +body[:batches][0][:objects][1][:item_data] = {} +body[:batches][0][:objects][1][:item_data][:name] = 'Coffee' +body[:batches][0][:objects][1][:item_data][:description] = 'Hot Bean Juice' +body[:batches][0][:objects][1][:item_data][:category_id] = '#Beverages' +body[:batches][0][:objects][1][:item_data][:tax_ids] = ['#SalesTax'] +body[:batches][0][:objects][1][:item_data][:variations] = [] + + +body[:batches][0][:objects][1][:item_data][:variations][0] = {} +body[:batches][0][:objects][1][:item_data][:variations][0][:type] = 'ITEM_VARIATION' +body[:batches][0][:objects][1][:item_data][:variations][0][:id] = '#Coffee_Regular' +body[:batches][0][:objects][1][:item_data][:variations][0][:present_at_all_locations] = true + +body[:batches][0][:objects][1][:item_data][:variations][1] = {} +body[:batches][0][:objects][1][:item_data][:variations][1][:type] = 'ITEM_VARIATION' +body[:batches][0][:objects][1][:item_data][:variations][1][:id] = '#Coffee_Large' +body[:batches][0][:objects][1][:item_data][:variations][1][:present_at_all_locations] = true + + +body[:batches][0][:objects][2] = {} +body[:batches][0][:objects][2][:type] = 'CATEGORY' +body[:batches][0][:objects][2][:id] = '#Beverages' +body[:batches][0][:objects][2][:present_at_all_locations] = true + +body[:batches][0][:objects][3] = {} +body[:batches][0][:objects][3][:type] = 'TAX' +body[:batches][0][:objects][3][:id] = '#SalesTax' +body[:batches][0][:objects][3][:present_at_all_locations] = true + + + +result = catalog_api.batch_upsert_catalog_objects(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Catalog Info + +Returns information about the Square Catalog API, such as batch size +limits for `BatchUpsertCatalogObjects`. + +```ruby +def catalog_info +``` + +### Response Type + +[`Catalog Info Response Hash`](/doc/models/catalog-info-response.md) + +### Example Usage + +```ruby +result = catalog_api.catalog_info() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Catalog + +Returns a list of [CatalogObject](#type-catalogobject)s that includes +all objects of a set of desired types (for example, all [CatalogItem](#type-catalogitem) +and [CatalogTax](#type-catalogtax) objects) in the catalog. The `types` parameter +is specified as a comma-separated list of valid [CatalogObject](#type-catalogobject) types: +`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`. + +__Important:__ ListCatalog does not return deleted catalog items. To retrieve +deleted catalog items, use SearchCatalogObjects and set `include_deleted_objects` +to `true`. + +```ruby +def list_catalog(cursor: nil, + types: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `cursor` | `String` | Query, Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `types` | `String` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve, for example
`ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.

The legal values are taken from the [CatalogObjectType](#type-catalogobjecttype)
enumeration, namely `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, or `IMAGE`. | + +### Response Type + +[`List Catalog Response Hash`](/doc/models/list-catalog-response.md) + +### Example Usage + +```ruby +result = catalog_api.list_catalog() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Upsert Catalog Object + +Creates or updates the target [CatalogObject](#type-catalogobject). + +```ruby +def upsert_catalog_object(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Upsert Catalog Object Request Hash`](/doc/models/upsert-catalog-object-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Upsert Catalog Object Response Hash`](/doc/models/upsert-catalog-object-response.md) + +### Example Usage + +```ruby +body = {} +body[:idempotency_key] = 'af3d1afc-7212-4300-b463-0bfc5314a5ae' +body[:object] = {} +body[:object][:type] = 'ITEM' +body[:object][:id] = '#Cocoa' +body[:object][:item_data] = {} +body[:object][:item_data][:name] = 'Cocoa' +body[:object][:item_data][:description] = 'Hot chocolate' +body[:object][:item_data][:abbreviation] = 'Ch' + +result = catalog_api.upsert_catalog_object(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Catalog Object + +Deletes a single [CatalogObject](#type-catalogobject) based on the +provided ID and returns the set of successfully deleted IDs in the response. +Deletion is a cascading event such that all children of the targeted object +are also deleted. For example, deleting a [CatalogItem](#type-catalogitem) +will also delete all of its +[CatalogItemVariation](#type-catalogitemvariation) children. + +```ruby +def delete_catalog_object(object_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `object_id` | `String` | Template, Required | The ID of the [CatalogObject](#type-catalogobject) to be deleted. When an object is deleted, other
objects in the graph that depend on that object will be deleted as well (for example, deleting a
[CatalogItem](#type-catalogitem) will delete its [CatalogItemVariation](#type-catalogitemvariation)s). | + +### Response Type + +[`Delete Catalog Object Response Hash`](/doc/models/delete-catalog-object-response.md) + +### Example Usage + +```ruby +object_id = 'object_id8' + +result = catalog_api.delete_catalog_object(object_id: object_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Catalog Object + +Returns a single [CatalogItem](#type-catalogitem) as a +[CatalogObject](#type-catalogobject) based on the provided ID. The returned +object includes all of the relevant [CatalogItem](#type-catalogitem) +information including: [CatalogItemVariation](#type-catalogitemvariation) +children, references to its +[CatalogModifierList](#type-catalogmodifierlist) objects, and the ids of +any [CatalogTax](#type-catalogtax) objects that apply to it. + +```ruby +def retrieve_catalog_object(object_id:, + include_related_objects: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `object_id` | `String` | Template, Required | The object ID of any type of [CatalogObject](#type-catalogobject)s to be retrieved. | +| `include_related_objects` | `Boolean` | Query, Optional | If `true`, the response will include additional objects that are related to the
requested object, as follows:

If the `object` field of the response contains a [CatalogItem](#type-catalogitem),
its associated [CatalogCategory](#type-catalogcategory), [CatalogTax](#type-catalogtax)es,
[CatalogImage](#type-catalogimage)s and [CatalogModifierList](#type-catalogmodifierlist)s
will be returned in the `related_objects` field of the response. If the `object`
field of the response contains a [CatalogItemVariation](#type-catalogitemvariation),
its parent [CatalogItem](#type-catalogitem) will be returned in the `related_objects` field of
the response.

Default value: `false` | + +### Response Type + +[`Retrieve Catalog Object Response Hash`](/doc/models/retrieve-catalog-object-response.md) + +### Example Usage + +```ruby +object_id = 'object_id8' + +result = catalog_api.retrieve_catalog_object(object_id: object_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Search Catalog Objects + +Queries the targeted catalog using a variety of query types: +[CatalogQuerySortedAttribute](#type-catalogquerysortedattribute), +[CatalogQueryExact](#type-catalogqueryexact), +[CatalogQueryRange](#type-catalogqueryrange), +[CatalogQueryText](#type-catalogquerytext), +[CatalogQueryItemsForTax](#type-catalogqueryitemsfortax), and +[CatalogQueryItemsForModifierList](#type-catalogqueryitemsformodifierlist). + +```ruby +def search_catalog_objects(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Search Catalog Objects Request Hash`](/doc/models/search-catalog-objects-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Search Catalog Objects Response Hash`](/doc/models/search-catalog-objects-response.md) + +### Example Usage + +```ruby +body = {} +body[:object_types] = ['ITEM'] +body[:query] = {} +body[:query][:prefix_query] = {} +body[:query][:prefix_query][:attribute_name] = 'name' +body[:query][:prefix_query][:attribute_prefix] = 'tea' +body[:limit] = 100 + +result = catalog_api.search_catalog_objects(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Item Modifier Lists + +Updates the [CatalogModifierList](#type-catalogmodifierlist) objects +that apply to the targeted [CatalogItem](#type-catalogitem) without having +to perform an upsert on the entire item. + +```ruby +def update_item_modifier_lists(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Update Item Modifier Lists Request Hash`](/doc/models/update-item-modifier-lists-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Update Item Modifier Lists Response Hash`](/doc/models/update-item-modifier-lists-response.md) + +### Example Usage + +```ruby +body = {} +body[:item_ids] = ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'] +body[:modifier_lists_to_enable] = ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'] +body[:modifier_lists_to_disable] = ['7WRC16CJZDVLSNDQ35PP6YAD'] + +result = catalog_api.update_item_modifier_lists(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Item Taxes + +Updates the [CatalogTax](#type-catalogtax) objects that apply to the +targeted [CatalogItem](#type-catalogitem) without having to perform an +upsert on the entire item. + +```ruby +def update_item_taxes(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Update Item Taxes Request Hash`](/doc/models/update-item-taxes-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Update Item Taxes Response Hash`](/doc/models/update-item-taxes-response.md) + +### Example Usage + +```ruby +body = {} +body[:item_ids] = ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'] +body[:taxes_to_enable] = ['4WRCNHCJZDVLSNDQ35PP6YAD'] +body[:taxes_to_disable] = ['AQCEGCEBBQONINDOHRGZISEX'] + +result = catalog_api.update_item_taxes(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/checkout.md b/doc/checkout.md index 774016d4..a774a26f 100644 --- a/doc/checkout.md +++ b/doc/checkout.md @@ -1,134 +1,134 @@ -# Checkout - -```ruby -checkout_api = client.checkout -``` - -## Class Name - -`CheckoutApi` - -## Create Checkout - -Links a `checkoutId` to a `checkout_page_url` that customers will -be directed to in order to provide their payment information using a -payment processing workflow hosted on connect.squareup.com. - -```ruby -def create_checkout(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the business location to associate the checkout with. | -| `body` | [`Create Checkout Request Hash`](/doc/models/create-checkout-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Create Checkout Response Hash`](/doc/models/create-checkout-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} -body[:idempotency_key] = '86ae1696-b1e3-4328-af6d-f1e04d947ad6' -body[:order] = {} -body[:order][:reference_id] = 'reference_id' -body[:order][:line_items] = [] - - -body[:order][:line_items][0] = {} -body[:order][:line_items][0][:name] = 'Printed T Shirt' -body[:order][:line_items][0][:quantity] = '2' -body[:order][:line_items][0][:base_price_money] = {} -body[:order][:line_items][0][:base_price_money][:amount] = 1500 -body[:order][:line_items][0][:base_price_money][:currency] = 'USD' -body[:order][:line_items][0][:discounts] = [] - - -body[:order][:line_items][0][:discounts][0] = {} -body[:order][:line_items][0][:discounts][0][:name] = '7% off previous season item' -body[:order][:line_items][0][:discounts][0][:percentage] = '7' - -body[:order][:line_items][0][:discounts][1] = {} -body[:order][:line_items][0][:discounts][1][:name] = '$3 off Customer Discount' - - -body[:order][:line_items][1] = {} -body[:order][:line_items][1][:name] = 'Slim Jeans' -body[:order][:line_items][1][:quantity] = '1' -body[:order][:line_items][1][:base_price_money] = {} -body[:order][:line_items][1][:base_price_money][:amount] = 2500 -body[:order][:line_items][1][:base_price_money][:currency] = 'USD' - -body[:order][:line_items][2] = {} -body[:order][:line_items][2][:name] = 'Woven Sweater' -body[:order][:line_items][2][:quantity] = '3' -body[:order][:line_items][2][:base_price_money] = {} -body[:order][:line_items][2][:base_price_money][:amount] = 3500 -body[:order][:line_items][2][:base_price_money][:currency] = 'USD' -body[:order][:line_items][2][:taxes] = [] - - -body[:order][:line_items][2][:taxes][0] = {} -body[:order][:line_items][2][:taxes][0][:name] = 'Fair Trade Tax' -body[:order][:line_items][2][:taxes][0][:percentage] = '5' - -body[:order][:line_items][2][:discounts] = [] - - -body[:order][:line_items][2][:discounts][0] = {} -body[:order][:line_items][2][:discounts][0][:name] = '$11 off Customer Discount' - - -body[:order][:taxes] = [] - - -body[:order][:taxes][0] = {} -body[:order][:taxes][0][:name] = 'Sales Tax' -body[:order][:taxes][0][:percentage] = '8.5' - -body[:order][:discounts] = [] - - -body[:order][:discounts][0] = {} -body[:order][:discounts][0][:name] = 'Father\'s day 12% OFF' -body[:order][:discounts][0][:percentage] = '12' - -body[:order][:discounts][1] = {} -body[:order][:discounts][1][:name] = 'Global Sales $55 OFF' - -body[:ask_for_shipping_address] = true -body[:merchant_support_email] = 'merchant+support@website.com' -body[:pre_populate_buyer_email] = 'example@email.com' -body[:pre_populate_shipping_address] = {} -body[:pre_populate_shipping_address][:address_line_1] = '1455 Market St.' -body[:pre_populate_shipping_address][:address_line_2] = 'Suite 600' -body[:pre_populate_shipping_address][:locality] = 'San Francisco' -body[:pre_populate_shipping_address][:administrative_district_level_1] = 'CA' -body[:pre_populate_shipping_address][:postal_code] = '94103' -body[:pre_populate_shipping_address][:country] = 'US' -body[:pre_populate_shipping_address][:first_name] = 'Jane' -body[:pre_populate_shipping_address][:last_name] = 'Doe' -body[:redirect_url] = 'https://merchant.website.com/order-confirm' -body[:additional_recipients] = [] - - -body[:additional_recipients][0] = {} -body[:additional_recipients][0][:location_id] = '057P5VYJ4A5X1' -body[:additional_recipients][0][:description] = 'Application fees' - - -result = checkout_api.create_checkout(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Checkout + +```ruby +checkout_api = client.checkout +``` + +## Class Name + +`CheckoutApi` + +## Create Checkout + +Links a `checkoutId` to a `checkout_page_url` that customers will +be directed to in order to provide their payment information using a +payment processing workflow hosted on connect.squareup.com. + +```ruby +def create_checkout(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the business location to associate the checkout with. | +| `body` | [`Create Checkout Request Hash`](/doc/models/create-checkout-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Create Checkout Response Hash`](/doc/models/create-checkout-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} +body[:idempotency_key] = '86ae1696-b1e3-4328-af6d-f1e04d947ad6' +body[:order] = {} +body[:order][:reference_id] = 'reference_id' +body[:order][:line_items] = [] + + +body[:order][:line_items][0] = {} +body[:order][:line_items][0][:name] = 'Printed T Shirt' +body[:order][:line_items][0][:quantity] = '2' +body[:order][:line_items][0][:base_price_money] = {} +body[:order][:line_items][0][:base_price_money][:amount] = 1500 +body[:order][:line_items][0][:base_price_money][:currency] = 'USD' +body[:order][:line_items][0][:discounts] = [] + + +body[:order][:line_items][0][:discounts][0] = {} +body[:order][:line_items][0][:discounts][0][:name] = '7% off previous season item' +body[:order][:line_items][0][:discounts][0][:percentage] = '7' + +body[:order][:line_items][0][:discounts][1] = {} +body[:order][:line_items][0][:discounts][1][:name] = '$3 off Customer Discount' + + +body[:order][:line_items][1] = {} +body[:order][:line_items][1][:name] = 'Slim Jeans' +body[:order][:line_items][1][:quantity] = '1' +body[:order][:line_items][1][:base_price_money] = {} +body[:order][:line_items][1][:base_price_money][:amount] = 2500 +body[:order][:line_items][1][:base_price_money][:currency] = 'USD' + +body[:order][:line_items][2] = {} +body[:order][:line_items][2][:name] = 'Woven Sweater' +body[:order][:line_items][2][:quantity] = '3' +body[:order][:line_items][2][:base_price_money] = {} +body[:order][:line_items][2][:base_price_money][:amount] = 3500 +body[:order][:line_items][2][:base_price_money][:currency] = 'USD' +body[:order][:line_items][2][:taxes] = [] + + +body[:order][:line_items][2][:taxes][0] = {} +body[:order][:line_items][2][:taxes][0][:name] = 'Fair Trade Tax' +body[:order][:line_items][2][:taxes][0][:percentage] = '5' + +body[:order][:line_items][2][:discounts] = [] + + +body[:order][:line_items][2][:discounts][0] = {} +body[:order][:line_items][2][:discounts][0][:name] = '$11 off Customer Discount' + + +body[:order][:taxes] = [] + + +body[:order][:taxes][0] = {} +body[:order][:taxes][0][:name] = 'Sales Tax' +body[:order][:taxes][0][:percentage] = '8.5' + +body[:order][:discounts] = [] + + +body[:order][:discounts][0] = {} +body[:order][:discounts][0][:name] = 'Father\'s day 12% OFF' +body[:order][:discounts][0][:percentage] = '12' + +body[:order][:discounts][1] = {} +body[:order][:discounts][1][:name] = 'Global Sales $55 OFF' + +body[:ask_for_shipping_address] = true +body[:merchant_support_email] = 'merchant+support@website.com' +body[:pre_populate_buyer_email] = 'example@email.com' +body[:pre_populate_shipping_address] = {} +body[:pre_populate_shipping_address][:address_line_1] = '1455 Market St.' +body[:pre_populate_shipping_address][:address_line_2] = 'Suite 600' +body[:pre_populate_shipping_address][:locality] = 'San Francisco' +body[:pre_populate_shipping_address][:administrative_district_level_1] = 'CA' +body[:pre_populate_shipping_address][:postal_code] = '94103' +body[:pre_populate_shipping_address][:country] = 'US' +body[:pre_populate_shipping_address][:first_name] = 'Jane' +body[:pre_populate_shipping_address][:last_name] = 'Doe' +body[:redirect_url] = 'https://merchant.website.com/order-confirm' +body[:additional_recipients] = [] + + +body[:additional_recipients][0] = {} +body[:additional_recipients][0][:location_id] = '057P5VYJ4A5X1' +body[:additional_recipients][0][:description] = 'Application fees' + + +result = checkout_api.create_checkout(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/customers.md b/doc/customers.md index b7c6f73b..17f35a33 100644 --- a/doc/customers.md +++ b/doc/customers.md @@ -1,354 +1,354 @@ -# Customers - -```ruby -customers_api = client.customers -``` - -## Class Name - -`CustomersApi` - -## Methods - -* [List Customers](/doc/customers.md#list-customers) -* [Create Customer](/doc/customers.md#create-customer) -* [Search Customers](/doc/customers.md#search-customers) -* [Delete Customer](/doc/customers.md#delete-customer) -* [Retrieve Customer](/doc/customers.md#retrieve-customer) -* [Update Customer](/doc/customers.md#update-customer) -* [Create Customer Card](/doc/customers.md#create-customer-card) -* [Delete Customer Card](/doc/customers.md#delete-customer-card) - -## List Customers - -Lists a business's customers. - -```ruby -def list_customers(cursor: nil, - sort_field: nil, - sort_order: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](/basics/api101/pagination) for more information. | -| `sort_field` | [`String (Customer Sort Field)`](/doc/models/customer-sort-field.md) | Query, Optional | Indicates how Customers should be sorted. Default: `DEFAULT`. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | Indicates whether Customers should be sorted in ascending (`ASC`) or
descending (`DESC`) order. Default: `ASC`. | - -### Response Type - -[`List Customers Response Hash`](/doc/models/list-customers-response.md) - -### Example Usage - -```ruby -result = customers_api.list_customers() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Customer - -Creates a new customer for a business, which can have associated cards on file. - -You must provide __at least one__ of the following values in your request to this -endpoint: - -- `given_name` -- `family_name` -- `company_name` -- `email_address` -- `phone_number` - -```ruby -def create_customer(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Create Customer Request Hash`](/doc/models/create-customer-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Create Customer Response Hash`](/doc/models/create-customer-response.md) - -### Example Usage - -```ruby -body = {} -body[:given_name] = 'Amelia' -body[:family_name] = 'Earhart' -body[:email_address] = 'Amelia.Earhart@example.com' -body[:address] = {} -body[:address][:address_line_1] = '500 Electric Ave' -body[:address][:address_line_2] = 'Suite 600' -body[:address][:locality] = 'New York' -body[:address][:administrative_district_level_1] = 'NY' -body[:address][:postal_code] = '10003' -body[:address][:country] = 'US' -body[:phone_number] = '1-212-555-4240' -body[:reference_id] = 'YOUR_REFERENCE_ID' -body[:note] = 'a customer' - -result = customers_api.create_customer(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Search Customers - -Searches the customer profiles associated with a Square account. -Calling SearchCustomers without an explicit query parameter returns all -customer profiles ordered alphabetically based on `given_name` and -`family_name`. - -```ruby -def search_customers(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Search Customers Request Hash`](/doc/models/search-customers-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Search Customers Response Hash`](/doc/models/search-customers-response.md) - -### Example Usage - -```ruby -body = {} -body[:limit] = 2 -body[:query] = {} -body[:query][:filter] = {} -body[:query][:filter][:creation_source] = {} -body[:query][:filter][:creation_source][:values] = ['THIRD_PARTY'] -body[:query][:filter][:creation_source][:rule] = 'INCLUDE' -body[:query][:filter][:created_at] = {} -body[:query][:filter][:created_at][:start_at] = '2018-01-01T00:00:00-00:00' -body[:query][:filter][:created_at][:end_at] = '2018-02-01T00:00:00-00:00' -body[:query][:sort] = {} -body[:query][:sort][:field] = 'CREATED_AT' -body[:query][:sort][:order] = 'ASC' - -result = customers_api.search_customers(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Customer - -Deletes a customer from a business, along with any linked cards on file. When two profiles -are merged into a single profile, that profile is assigned a new `customer_id`. You must use the -new `customer_id` to delete merged profiles. - -```ruby -def delete_customer(customer_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `customer_id` | `String` | Template, Required | The ID of the customer to delete. | - -### Response Type - -[`Delete Customer Response Hash`](/doc/models/delete-customer-response.md) - -### Example Usage - -```ruby -customer_id = 'customer_id8' - -result = customers_api.delete_customer(customer_id: customer_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Customer - -Returns details for a single customer. - -```ruby -def retrieve_customer(customer_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `customer_id` | `String` | Template, Required | The ID of the customer to retrieve. | - -### Response Type - -[`Retrieve Customer Response Hash`](/doc/models/retrieve-customer-response.md) - -### Example Usage - -```ruby -customer_id = 'customer_id8' - -result = customers_api.retrieve_customer(customer_id: customer_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Customer - -Updates the details of an existing customer. When two profiles are merged -into a single profile, that profile is assigned a new `customer_id`. You must use -the new `customer_id` to update merged profiles. - -You cannot edit a customer's cards on file with this endpoint. To make changes -to a card on file, you must delete the existing card on file with the -[DeleteCustomerCard](/doc/customers.md#deletecustomercard) endpoint, then -create a new one with the -[CreateCustomerCard](/doc/customers.md#createcustomercard) endpoint. - -```ruby -def update_customer(customer_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `customer_id` | `String` | Template, Required | The ID of the customer to update. | -| `body` | [`Update Customer Request Hash`](/doc/models/update-customer-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Update Customer Response Hash`](/doc/models/update-customer-response.md) - -### Example Usage - -```ruby -customer_id = 'customer_id8' -body = {} -body[:email_address] = 'New.Amelia.Earhart@example.com' -body[:phone_number] = '' -body[:note] = 'updated customer note' - -result = customers_api.update_customer(customer_id: customer_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Customer Card - -Adds a card on file to an existing customer. - -As with charges, calls to `CreateCustomerCard` are idempotent. Multiple -calls with the same card nonce return the same card record that was created -with the provided nonce during the _first_ call. - -Cards on file are automatically updated on a monthly basis to confirm they -are still valid and can be charged. - -```ruby -def create_customer_card(customer_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `customer_id` | `String` | Template, Required | The Square ID of the customer profile the card is linked to. | -| `body` | [`Create Customer Card Request Hash`](/doc/models/create-customer-card-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Create Customer Card Response Hash`](/doc/models/create-customer-card-response.md) - -### Example Usage - -```ruby -customer_id = 'customer_id8' -body = {} -body[:card_nonce] = 'YOUR_CARD_NONCE' -body[:billing_address] = {} -body[:billing_address][:address_line_1] = '500 Electric Ave' -body[:billing_address][:address_line_2] = 'Suite 600' -body[:billing_address][:locality] = 'New York' -body[:billing_address][:administrative_district_level_1] = 'NY' -body[:billing_address][:postal_code] = '10003' -body[:billing_address][:country] = 'US' -body[:cardholder_name] = 'Amelia Earhart' - -result = customers_api.create_customer_card(customer_id: customer_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Customer Card - -Removes a card on file from a customer. - -```ruby -def delete_customer_card(customer_id:, - card_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `customer_id` | `String` | Template, Required | The ID of the customer that the card on file belongs to. | -| `card_id` | `String` | Template, Required | The ID of the card on file to delete. | - -### Response Type - -[`Delete Customer Card Response Hash`](/doc/models/delete-customer-card-response.md) - -### Example Usage - -```ruby -customer_id = 'customer_id8' -card_id = 'card_id4' - -result = customers_api.delete_customer_card(customer_id: customer_id, card_id: card_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Customers + +```ruby +customers_api = client.customers +``` + +## Class Name + +`CustomersApi` + +## Methods + +* [List Customers](/doc/customers.md#list-customers) +* [Create Customer](/doc/customers.md#create-customer) +* [Search Customers](/doc/customers.md#search-customers) +* [Delete Customer](/doc/customers.md#delete-customer) +* [Retrieve Customer](/doc/customers.md#retrieve-customer) +* [Update Customer](/doc/customers.md#update-customer) +* [Create Customer Card](/doc/customers.md#create-customer-card) +* [Delete Customer Card](/doc/customers.md#delete-customer-card) + +## List Customers + +Lists a business's customers. + +```ruby +def list_customers(cursor: nil, + sort_field: nil, + sort_order: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `sort_field` | [`String (Customer Sort Field)`](/doc/models/customer-sort-field.md) | Query, Optional | Indicates how Customers should be sorted. Default: `DEFAULT`. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | Indicates whether Customers should be sorted in ascending (`ASC`) or
descending (`DESC`) order. Default: `ASC`. | + +### Response Type + +[`List Customers Response Hash`](/doc/models/list-customers-response.md) + +### Example Usage + +```ruby +result = customers_api.list_customers() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Customer + +Creates a new customer for a business, which can have associated cards on file. + +You must provide __at least one__ of the following values in your request to this +endpoint: + +- `given_name` +- `family_name` +- `company_name` +- `email_address` +- `phone_number` + +```ruby +def create_customer(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Create Customer Request Hash`](/doc/models/create-customer-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Create Customer Response Hash`](/doc/models/create-customer-response.md) + +### Example Usage + +```ruby +body = {} +body[:given_name] = 'Amelia' +body[:family_name] = 'Earhart' +body[:email_address] = 'Amelia.Earhart@example.com' +body[:address] = {} +body[:address][:address_line_1] = '500 Electric Ave' +body[:address][:address_line_2] = 'Suite 600' +body[:address][:locality] = 'New York' +body[:address][:administrative_district_level_1] = 'NY' +body[:address][:postal_code] = '10003' +body[:address][:country] = 'US' +body[:phone_number] = '1-212-555-4240' +body[:reference_id] = 'YOUR_REFERENCE_ID' +body[:note] = 'a customer' + +result = customers_api.create_customer(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Search Customers + +Searches the customer profiles associated with a Square account. +Calling SearchCustomers without an explicit query parameter returns all +customer profiles ordered alphabetically based on `given_name` and +`family_name`. + +```ruby +def search_customers(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Search Customers Request Hash`](/doc/models/search-customers-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Search Customers Response Hash`](/doc/models/search-customers-response.md) + +### Example Usage + +```ruby +body = {} +body[:limit] = 2 +body[:query] = {} +body[:query][:filter] = {} +body[:query][:filter][:creation_source] = {} +body[:query][:filter][:creation_source][:values] = ['THIRD_PARTY'] +body[:query][:filter][:creation_source][:rule] = 'INCLUDE' +body[:query][:filter][:created_at] = {} +body[:query][:filter][:created_at][:start_at] = '2018-01-01T00:00:00-00:00' +body[:query][:filter][:created_at][:end_at] = '2018-02-01T00:00:00-00:00' +body[:query][:sort] = {} +body[:query][:sort][:field] = 'CREATED_AT' +body[:query][:sort][:order] = 'ASC' + +result = customers_api.search_customers(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Customer + +Deletes a customer from a business, along with any linked cards on file. When two profiles +are merged into a single profile, that profile is assigned a new `customer_id`. You must use the +new `customer_id` to delete merged profiles. + +```ruby +def delete_customer(customer_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `customer_id` | `String` | Template, Required | The ID of the customer to delete. | + +### Response Type + +[`Delete Customer Response Hash`](/doc/models/delete-customer-response.md) + +### Example Usage + +```ruby +customer_id = 'customer_id8' + +result = customers_api.delete_customer(customer_id: customer_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Customer + +Returns details for a single customer. + +```ruby +def retrieve_customer(customer_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `customer_id` | `String` | Template, Required | The ID of the customer to retrieve. | + +### Response Type + +[`Retrieve Customer Response Hash`](/doc/models/retrieve-customer-response.md) + +### Example Usage + +```ruby +customer_id = 'customer_id8' + +result = customers_api.retrieve_customer(customer_id: customer_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Customer + +Updates the details of an existing customer. When two profiles are merged +into a single profile, that profile is assigned a new `customer_id`. You must use +the new `customer_id` to update merged profiles. + +You cannot edit a customer's cards on file with this endpoint. To make changes +to a card on file, you must delete the existing card on file with the +[DeleteCustomerCard](#endpoint-customers-deletecustomercard) endpoint, then +create a new one with the +[CreateCustomerCard](#endpoint-customers-createcustomercard) endpoint. + +```ruby +def update_customer(customer_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `customer_id` | `String` | Template, Required | The ID of the customer to update. | +| `body` | [`Update Customer Request Hash`](/doc/models/update-customer-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Update Customer Response Hash`](/doc/models/update-customer-response.md) + +### Example Usage + +```ruby +customer_id = 'customer_id8' +body = {} +body[:email_address] = 'New.Amelia.Earhart@example.com' +body[:phone_number] = '' +body[:note] = 'updated customer note' + +result = customers_api.update_customer(customer_id: customer_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Customer Card + +Adds a card on file to an existing customer. + +As with charges, calls to `CreateCustomerCard` are idempotent. Multiple +calls with the same card nonce return the same card record that was created +with the provided nonce during the _first_ call. + +Cards on file are automatically updated on a monthly basis to confirm they +are still valid and can be charged. + +```ruby +def create_customer_card(customer_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `customer_id` | `String` | Template, Required | The Square ID of the customer profile the card is linked to. | +| `body` | [`Create Customer Card Request Hash`](/doc/models/create-customer-card-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Create Customer Card Response Hash`](/doc/models/create-customer-card-response.md) + +### Example Usage + +```ruby +customer_id = 'customer_id8' +body = {} +body[:card_nonce] = 'YOUR_CARD_NONCE' +body[:billing_address] = {} +body[:billing_address][:address_line_1] = '500 Electric Ave' +body[:billing_address][:address_line_2] = 'Suite 600' +body[:billing_address][:locality] = 'New York' +body[:billing_address][:administrative_district_level_1] = 'NY' +body[:billing_address][:postal_code] = '10003' +body[:billing_address][:country] = 'US' +body[:cardholder_name] = 'Amelia Earhart' + +result = customers_api.create_customer_card(customer_id: customer_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Customer Card + +Removes a card on file from a customer. + +```ruby +def delete_customer_card(customer_id:, + card_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `customer_id` | `String` | Template, Required | The ID of the customer that the card on file belongs to. | +| `card_id` | `String` | Template, Required | The ID of the card on file to delete. | + +### Response Type + +[`Delete Customer Card Response Hash`](/doc/models/delete-customer-card-response.md) + +### Example Usage + +```ruby +customer_id = 'customer_id8' +card_id = 'card_id4' + +result = customers_api.delete_customer_card(customer_id: customer_id, card_id: card_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/employees.md b/doc/employees.md index 234a814b..c3607681 100644 --- a/doc/employees.md +++ b/doc/employees.md @@ -1,83 +1,83 @@ -# Employees - -```ruby -employees_api = client.employees -``` - -## Class Name - -`EmployeesApi` - -## Methods - -* [List Employees](/doc/employees.md#list-employees) -* [Retrieve Employee](/doc/employees.md#retrieve-employee) - -## List Employees - -Gets a list of `Employee` objects for a business. - -```ruby -def list_employees(location_id: nil, - status: nil, - limit: nil, - cursor: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Query, Optional | Filter employees returned to only those that are associated with the
specified location. | -| `status` | [`String (Employee Status)`](/doc/models/employee-status.md) | Query, Optional | Specifies the EmployeeStatus to filter the employee by. | -| `limit` | `Integer` | Query, Optional | The number of employees to be returned on each page. | -| `cursor` | `String` | Query, Optional | The token required to retrieve the specified page of results. | - -### Response Type - -[`List Employees Response Hash`](/doc/models/list-employees-response.md) - -### Example Usage - -```ruby -result = employees_api.list_employees() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Employee - -Gets an `Employee` by Square-assigned employee `ID` (UUID) - -```ruby -def retrieve_employee(id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Template, Required | UUID for the employee that was requested. | - -### Response Type - -[`Retrieve Employee Response Hash`](/doc/models/retrieve-employee-response.md) - -### Example Usage - -```ruby -id = 'id0' - -result = employees_api.retrieve_employee(id: id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Employees + +```ruby +employees_api = client.employees +``` + +## Class Name + +`EmployeesApi` + +## Methods + +* [List Employees](/doc/employees.md#list-employees) +* [Retrieve Employee](/doc/employees.md#retrieve-employee) + +## List Employees + +Gets a list of `Employee` objects for a business. + +```ruby +def list_employees(location_id: nil, + status: nil, + limit: nil, + cursor: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Query, Optional | Filter employees returned to only those that are associated with the
specified location. | +| `status` | [`String (Employee Status)`](/doc/models/employee-status.md) | Query, Optional | Specifies the EmployeeStatus to filter the employee by. | +| `limit` | `Integer` | Query, Optional | The number of employees to be returned on each page. | +| `cursor` | `String` | Query, Optional | The token required to retrieve the specified page of results. | + +### Response Type + +[`List Employees Response Hash`](/doc/models/list-employees-response.md) + +### Example Usage + +```ruby +result = employees_api.list_employees() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Employee + +Gets an `Employee` by Square-assigned employee `ID` (UUID) + +```ruby +def retrieve_employee(id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Template, Required | UUID for the employee that was requested. | + +### Response Type + +[`Retrieve Employee Response Hash`](/doc/models/retrieve-employee-response.md) + +### Example Usage + +```ruby +id = 'id0' + +result = employees_api.retrieve_employee(id: id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/inventory.md b/doc/inventory.md index 84ae38f9..00ed07c9 100644 --- a/doc/inventory.md +++ b/doc/inventory.md @@ -1,312 +1,312 @@ -# Inventory - -```ruby -inventory_api = client.inventory -``` - -## Class Name - -`InventoryApi` - -## Methods - -* [Retrieve Inventory Adjustment](/doc/inventory.md#retrieve-inventory-adjustment) -* [Batch Change Inventory](/doc/inventory.md#batch-change-inventory) -* [Batch Retrieve Inventory Changes](/doc/inventory.md#batch-retrieve-inventory-changes) -* [Batch Retrieve Inventory Counts](/doc/inventory.md#batch-retrieve-inventory-counts) -* [Retrieve Inventory Physical Count](/doc/inventory.md#retrieve-inventory-physical-count) -* [Retrieve Inventory Count](/doc/inventory.md#retrieve-inventory-count) -* [Retrieve Inventory Changes](/doc/inventory.md#retrieve-inventory-changes) - -## Retrieve Inventory Adjustment - -Returns the [InventoryAdjustment](./models/inventory-adjustment.md) object -with the provided `adjustment_id`. - -```ruby -def retrieve_inventory_adjustment(adjustment_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `adjustment_id` | `String` | Template, Required | ID of the [InventoryAdjustment](./models/inventory-adjustment.md) to retrieve. | - -### Response Type - -[`Retrieve Inventory Adjustment Response Hash`](/doc/models/retrieve-inventory-adjustment-response.md) - -### Example Usage - -```ruby -adjustment_id = 'adjustment_id0' - -result = inventory_api.retrieve_inventory_adjustment(adjustment_id: adjustment_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Batch Change Inventory - -Applies adjustments and counts to the provided item quantities. - -On success: returns the current calculated counts for all objects -referenced in the request. -On failure: returns a list of related errors. - -```ruby -def batch_change_inventory(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Batch Change Inventory Request Hash`](/doc/models/batch-change-inventory-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Batch Change Inventory Response Hash`](/doc/models/batch-change-inventory-response.md) - -### Example Usage - -```ruby -body = {} -body[:idempotency_key] = '8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe' -body[:changes] = [] - - -body[:changes][0] = {} -body[:changes][0][:type] = 'PHYSICAL_COUNT' -body[:changes][0][:physical_count] = {} -body[:changes][0][:physical_count][:reference_id] = '1536bfbf-efed-48bf-b17d-a197141b2a92' -body[:changes][0][:physical_count][:catalog_object_id] = 'W62UWFY35CWMYGVWK6TWJDNI' -body[:changes][0][:physical_count][:state] = 'IN_STOCK' -body[:changes][0][:physical_count][:location_id] = 'C6W5YS5QM06F5' -body[:changes][0][:physical_count][:quantity] = '53' -body[:changes][0][:physical_count][:employee_id] = 'LRK57NSQ5X7PUD05' -body[:changes][0][:physical_count][:occurred_at] = '2016-11-16T22:25:24.878Z' - -body[:ignore_unchanged_counts] = true - -result = inventory_api.batch_change_inventory(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Batch Retrieve Inventory Changes - -Returns historical physical counts and adjustments based on the -provided filter criteria. - -Results are paginated and sorted in ascending order according their -`occurred_at` timestamp (oldest first). - -BatchRetrieveInventoryChanges is a catch-all query endpoint for queries -that cannot be handled by other, simpler endpoints. - -```ruby -def batch_retrieve_inventory_changes(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Batch Retrieve Inventory Changes Request Hash`](/doc/models/batch-retrieve-inventory-changes-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Batch Retrieve Inventory Changes Response Hash`](/doc/models/batch-retrieve-inventory-changes-response.md) - -### Example Usage - -```ruby -body = {} -body[:catalog_object_ids] = ['W62UWFY35CWMYGVWK6TWJDNI'] -body[:location_ids] = ['C6W5YS5QM06F5'] -body[:types] = ['PHYSICAL_COUNT'] -body[:states] = ['IN_STOCK'] -body[:updated_after] = '2016-11-01T00:00:00.000Z' -body[:updated_before] = '2016-12-01T00:00:00.000Z' - -result = inventory_api.batch_retrieve_inventory_changes(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Batch Retrieve Inventory Counts - -Returns current counts for the provided -[CatalogObject](./models/catalog-object.md)s at the requested -[Location](./models/location.md)s. - -Results are paginated and sorted in descending order according to their -`calculated_at` timestamp (newest first). - -When `updated_after` is specified, only counts that have changed since that -time (based on the server timestamp for the most recent change) are -returned. This allows clients to perform a "sync" operation, for example -in response to receiving a Webhook notification. - -```ruby -def batch_retrieve_inventory_counts(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Batch Retrieve Inventory Counts Request Hash`](/doc/models/batch-retrieve-inventory-counts-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Batch Retrieve Inventory Counts Response Hash`](/doc/models/batch-retrieve-inventory-counts-response.md) - -### Example Usage - -```ruby -body = {} -body[:catalog_object_ids] = ['W62UWFY35CWMYGVWK6TWJDNI'] -body[:location_ids] = ['59TNP9SA8VGDA'] -body[:updated_after] = '2016-11-16T00:00:00.000Z' - -result = inventory_api.batch_retrieve_inventory_counts(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Inventory Physical Count - -Returns the [InventoryPhysicalCount](./models/inventory-physical-count.md) -object with the provided `physical_count_id`. - -```ruby -def retrieve_inventory_physical_count(physical_count_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `physical_count_id` | `String` | Template, Required | ID of the
[InventoryPhysicalCount](./models/inventory-physical-count.md) to retrieve. | - -### Response Type - -[`Retrieve Inventory Physical Count Response Hash`](/doc/models/retrieve-inventory-physical-count-response.md) - -### Example Usage - -```ruby -physical_count_id = 'physical_count_id2' - -result = inventory_api.retrieve_inventory_physical_count(physical_count_id: physical_count_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Inventory Count - -Retrieves the current calculated stock count for a given -[CatalogObject](./models/catalog-object.md) at a given set of -[Location](./models/location.md)s. Responses are paginated and unsorted. -For more sophisticated queries, use a batch endpoint. - -```ruby -def retrieve_inventory_count(catalog_object_id:, - location_ids: nil, - cursor: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `catalog_object_id` | `String` | Template, Required | ID of the [CatalogObject](./models/catalog-object.md) to retrieve. | -| `location_ids` | `String` | Query, Optional | The [Location](./models/location.md) IDs to look up as a comma-separated
list. An empty list queries all locations. | -| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](/basics/api101/pagination) for more information. | - -### Response Type - -[`Retrieve Inventory Count Response Hash`](/doc/models/retrieve-inventory-count-response.md) - -### Example Usage - -```ruby -catalog_object_id = 'catalog_object_id6' - -result = inventory_api.retrieve_inventory_count(catalog_object_id: catalog_object_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Inventory Changes - -Returns a set of physical counts and inventory adjustments for the -provided [CatalogObject](./models/catalog-object.md) at the requested -[Location](./models/location.md)s. - -Results are paginated and sorted in descending order according to their -`occurred_at` timestamp (newest first). - -There are no limits on how far back the caller can page. This endpoint is -useful when displaying recent changes for a specific item. For more -sophisticated queries, use a batch endpoint. - -```ruby -def retrieve_inventory_changes(catalog_object_id:, - location_ids: nil, - cursor: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `catalog_object_id` | `String` | Template, Required | ID of the [CatalogObject](./models/catalog-object.md) to retrieve. | -| `location_ids` | `String` | Query, Optional | The [Location](./models/location.md) IDs to look up as a comma-separated
list. An empty list queries all locations. | -| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](/basics/api101/pagination) for more information. | - -### Response Type - -[`Retrieve Inventory Changes Response Hash`](/doc/models/retrieve-inventory-changes-response.md) - -### Example Usage - -```ruby -catalog_object_id = 'catalog_object_id6' - -result = inventory_api.retrieve_inventory_changes(catalog_object_id: catalog_object_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Inventory + +```ruby +inventory_api = client.inventory +``` + +## Class Name + +`InventoryApi` + +## Methods + +* [Retrieve Inventory Adjustment](/doc/inventory.md#retrieve-inventory-adjustment) +* [Batch Change Inventory](/doc/inventory.md#batch-change-inventory) +* [Batch Retrieve Inventory Changes](/doc/inventory.md#batch-retrieve-inventory-changes) +* [Batch Retrieve Inventory Counts](/doc/inventory.md#batch-retrieve-inventory-counts) +* [Retrieve Inventory Physical Count](/doc/inventory.md#retrieve-inventory-physical-count) +* [Retrieve Inventory Count](/doc/inventory.md#retrieve-inventory-count) +* [Retrieve Inventory Changes](/doc/inventory.md#retrieve-inventory-changes) + +## Retrieve Inventory Adjustment + +Returns the [InventoryAdjustment](#type-inventoryadjustment) object +with the provided `adjustment_id`. + +```ruby +def retrieve_inventory_adjustment(adjustment_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `adjustment_id` | `String` | Template, Required | ID of the [InventoryAdjustment](#type-inventoryadjustment) to retrieve. | + +### Response Type + +[`Retrieve Inventory Adjustment Response Hash`](/doc/models/retrieve-inventory-adjustment-response.md) + +### Example Usage + +```ruby +adjustment_id = 'adjustment_id0' + +result = inventory_api.retrieve_inventory_adjustment(adjustment_id: adjustment_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Batch Change Inventory + +Applies adjustments and counts to the provided item quantities. + +On success: returns the current calculated counts for all objects +referenced in the request. +On failure: returns a list of related errors. + +```ruby +def batch_change_inventory(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Batch Change Inventory Request Hash`](/doc/models/batch-change-inventory-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Batch Change Inventory Response Hash`](/doc/models/batch-change-inventory-response.md) + +### Example Usage + +```ruby +body = {} +body[:idempotency_key] = '8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe' +body[:changes] = [] + + +body[:changes][0] = {} +body[:changes][0][:type] = 'PHYSICAL_COUNT' +body[:changes][0][:physical_count] = {} +body[:changes][0][:physical_count][:reference_id] = '1536bfbf-efed-48bf-b17d-a197141b2a92' +body[:changes][0][:physical_count][:catalog_object_id] = 'W62UWFY35CWMYGVWK6TWJDNI' +body[:changes][0][:physical_count][:state] = 'IN_STOCK' +body[:changes][0][:physical_count][:location_id] = 'C6W5YS5QM06F5' +body[:changes][0][:physical_count][:quantity] = '53' +body[:changes][0][:physical_count][:employee_id] = 'LRK57NSQ5X7PUD05' +body[:changes][0][:physical_count][:occurred_at] = '2016-11-16T22:25:24.878Z' + +body[:ignore_unchanged_counts] = true + +result = inventory_api.batch_change_inventory(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Batch Retrieve Inventory Changes + +Returns historical physical counts and adjustments based on the +provided filter criteria. + +Results are paginated and sorted in ascending order according their +`occurred_at` timestamp (oldest first). + +BatchRetrieveInventoryChanges is a catch-all query endpoint for queries +that cannot be handled by other, simpler endpoints. + +```ruby +def batch_retrieve_inventory_changes(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Batch Retrieve Inventory Changes Request Hash`](/doc/models/batch-retrieve-inventory-changes-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Batch Retrieve Inventory Changes Response Hash`](/doc/models/batch-retrieve-inventory-changes-response.md) + +### Example Usage + +```ruby +body = {} +body[:catalog_object_ids] = ['W62UWFY35CWMYGVWK6TWJDNI'] +body[:location_ids] = ['C6W5YS5QM06F5'] +body[:types] = ['PHYSICAL_COUNT'] +body[:states] = ['IN_STOCK'] +body[:updated_after] = '2016-11-01T00:00:00.000Z' +body[:updated_before] = '2016-12-01T00:00:00.000Z' + +result = inventory_api.batch_retrieve_inventory_changes(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Batch Retrieve Inventory Counts + +Returns current counts for the provided +[CatalogObject](#type-catalogobject)s at the requested +[Location](#type-location)s. + +Results are paginated and sorted in descending order according to their +`calculated_at` timestamp (newest first). + +When `updated_after` is specified, only counts that have changed since that +time (based on the server timestamp for the most recent change) are +returned. This allows clients to perform a "sync" operation, for example +in response to receiving a Webhook notification. + +```ruby +def batch_retrieve_inventory_counts(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Batch Retrieve Inventory Counts Request Hash`](/doc/models/batch-retrieve-inventory-counts-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Batch Retrieve Inventory Counts Response Hash`](/doc/models/batch-retrieve-inventory-counts-response.md) + +### Example Usage + +```ruby +body = {} +body[:catalog_object_ids] = ['W62UWFY35CWMYGVWK6TWJDNI'] +body[:location_ids] = ['59TNP9SA8VGDA'] +body[:updated_after] = '2016-11-16T00:00:00.000Z' + +result = inventory_api.batch_retrieve_inventory_counts(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Inventory Physical Count + +Returns the [InventoryPhysicalCount](#type-inventoryphysicalcount) +object with the provided `physical_count_id`. + +```ruby +def retrieve_inventory_physical_count(physical_count_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `physical_count_id` | `String` | Template, Required | ID of the
[InventoryPhysicalCount](#type-inventoryphysicalcount) to retrieve. | + +### Response Type + +[`Retrieve Inventory Physical Count Response Hash`](/doc/models/retrieve-inventory-physical-count-response.md) + +### Example Usage + +```ruby +physical_count_id = 'physical_count_id2' + +result = inventory_api.retrieve_inventory_physical_count(physical_count_id: physical_count_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Inventory Count + +Retrieves the current calculated stock count for a given +[CatalogObject](#type-catalogobject) at a given set of +[Location](#type-location)s. Responses are paginated and unsorted. +For more sophisticated queries, use a batch endpoint. + +```ruby +def retrieve_inventory_count(catalog_object_id:, + location_ids: nil, + cursor: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `catalog_object_id` | `String` | Template, Required | ID of the [CatalogObject](#type-catalogobject) to retrieve. | +| `location_ids` | `String` | Query, Optional | The [Location](#type-location) IDs to look up as a comma-separated
list. An empty list queries all locations. | +| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Response Type + +[`Retrieve Inventory Count Response Hash`](/doc/models/retrieve-inventory-count-response.md) + +### Example Usage + +```ruby +catalog_object_id = 'catalog_object_id6' + +result = inventory_api.retrieve_inventory_count(catalog_object_id: catalog_object_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Inventory Changes + +Returns a set of physical counts and inventory adjustments for the +provided [CatalogObject](#type-catalogobject) at the requested +[Location](#type-location)s. + +Results are paginated and sorted in descending order according to their +`occurred_at` timestamp (newest first). + +There are no limits on how far back the caller can page. This endpoint is +useful when displaying recent changes for a specific item. For more +sophisticated queries, use a batch endpoint. + +```ruby +def retrieve_inventory_changes(catalog_object_id:, + location_ids: nil, + cursor: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `catalog_object_id` | `String` | Template, Required | ID of the [CatalogObject](#type-catalogobject) to retrieve. | +| `location_ids` | `String` | Query, Optional | The [Location](#type-location) IDs to look up as a comma-separated
list. An empty list queries all locations. | +| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Response Type + +[`Retrieve Inventory Changes Response Hash`](/doc/models/retrieve-inventory-changes-response.md) + +### Example Usage + +```ruby +catalog_object_id = 'catalog_object_id6' + +result = inventory_api.retrieve_inventory_changes(catalog_object_id: catalog_object_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/labor.md b/doc/labor.md index f60872ee..6ac0be01 100644 --- a/doc/labor.md +++ b/doc/labor.md @@ -1,609 +1,609 @@ -# Labor - -```ruby -labor_api = client.labor -``` - -## Class Name - -`LaborApi` - -## Methods - -* [List Break Types](/doc/labor.md#list-break-types) -* [Create Break Type](/doc/labor.md#create-break-type) -* [Delete Break Type](/doc/labor.md#delete-break-type) -* [Get Break Type](/doc/labor.md#get-break-type) -* [Update Break Type](/doc/labor.md#update-break-type) -* [List Employee Wages](/doc/labor.md#list-employee-wages) -* [Get Employee Wage](/doc/labor.md#get-employee-wage) -* [Create Shift](/doc/labor.md#create-shift) -* [Search Shifts](/doc/labor.md#search-shifts) -* [Delete Shift](/doc/labor.md#delete-shift) -* [Get Shift](/doc/labor.md#get-shift) -* [Update Shift](/doc/labor.md#update-shift) -* [List Workweek Configs](/doc/labor.md#list-workweek-configs) -* [Update Workweek Config](/doc/labor.md#update-workweek-config) - -## List Break Types - -Returns a paginated list of `BreakType` instances for a business. - -```ruby -def list_break_types(location_id: nil, - limit: nil, - cursor: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Query, Optional | Filter Break Types returned to only those that are associated with the
specified location. | -| `limit` | `Integer` | Query, Optional | Maximum number of Break Types to return per page. Can range between 1
and 200. The default is the maximum at 200. | -| `cursor` | `String` | Query, Optional | Pointer to the next page of Break Type results to fetch. | - -### Response Type - -[`List Break Types Response Hash`](/doc/models/list-break-types-response.md) - -### Example Usage - -```ruby -result = labor_api.list_break_types() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Break Type - -Creates a new `BreakType`. - -A `BreakType` is a template for creating `Break` objects. -You must provide the following values in your request to this -endpoint: - -- `location_id` -- `break_name` -- `expected_duration` -- `is_paid` - -You can only have 3 `BreakType` instances per location. If you attempt to add a 4th -`BreakType` for a location, an `INVALID_REQUEST_ERROR` "Exceeded limit of 3 breaks per location." -is returned. - -```ruby -def create_break_type(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Create Break Type Request Hash`](/doc/models/create-break-type-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Create Break Type Response Hash`](/doc/models/create-break-type-response.md) - -### Example Usage - -```ruby -body = {} -body[:idempotency_key] = 'PAD3NG5KSN2GL' -body[:break_type] = {} -body[:break_type][:location_id] = 'CGJN03P1D08GF' -body[:break_type][:break_name] = 'Lunch Break' -body[:break_type][:expected_duration] = 'PT30M' -body[:break_type][:is_paid] = true - -result = labor_api.create_break_type(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Break Type - -Deletes an existing `BreakType`. - -A `BreakType` can be deleted even if it is referenced from a `Shift`. - -```ruby -def delete_break_type(id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Template, Required | UUID for the `BreakType` being deleted. | - -### Response Type - -[`Delete Break Type Response Hash`](/doc/models/delete-break-type-response.md) - -### Example Usage - -```ruby -id = 'id0' - -result = labor_api.delete_break_type(id: id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Get Break Type - -Returns a single `BreakType` specified by id. - -```ruby -def get_break_type(id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Template, Required | UUID for the `BreakType` being retrieved. | - -### Response Type - -[`Get Break Type Response Hash`](/doc/models/get-break-type-response.md) - -### Example Usage - -```ruby -id = 'id0' - -result = labor_api.get_break_type(id: id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Break Type - -Updates an existing `BreakType`. - -```ruby -def update_break_type(id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Template, Required | UUID for the `BreakType` being updated. | -| `body` | [`Update Break Type Request Hash`](/doc/models/update-break-type-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Update Break Type Response Hash`](/doc/models/update-break-type-response.md) - -### Example Usage - -```ruby -id = 'id0' -body = {} -body[:break_type] = {} -body[:break_type][:location_id] = '26M7H24AZ9N6R' -body[:break_type][:break_name] = 'Lunch' -body[:break_type][:expected_duration] = 'PT50M' -body[:break_type][:is_paid] = true -body[:break_type][:version] = 1 - -result = labor_api.update_break_type(id: id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Employee Wages - -Returns a paginated list of `EmployeeWage` instances for a business. - -```ruby -def list_employee_wages(employee_id: nil, - limit: nil, - cursor: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `employee_id` | `String` | Query, Optional | Filter wages returned to only those that are associated with the
specified employee. | -| `limit` | `Integer` | Query, Optional | Maximum number of Employee Wages to return per page. Can range between
1 and 200. The default is the maximum at 200. | -| `cursor` | `String` | Query, Optional | Pointer to the next page of Employee Wage results to fetch. | - -### Response Type - -[`List Employee Wages Response Hash`](/doc/models/list-employee-wages-response.md) - -### Example Usage - -```ruby -result = labor_api.list_employee_wages() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Get Employee Wage - -Returns a single `EmployeeWage` specified by id. - -```ruby -def get_employee_wage(id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Template, Required | UUID for the `EmployeeWage` being retrieved. | - -### Response Type - -[`Get Employee Wage Response Hash`](/doc/models/get-employee-wage-response.md) - -### Example Usage - -```ruby -id = 'id0' - -result = labor_api.get_employee_wage(id: id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Shift - -Creates a new `Shift`. - -A `Shift` represents a complete work day for a single employee. -You must provide the following values in your request to this -endpoint: - -- `location_id` -- `employee_id` -- `start_at` - -An attempt to create a new `Shift` can result in a `BAD_REQUEST` error when: -- The `status` of the new `Shift` is `OPEN` and the employee has another -shift with an `OPEN` status. -- The `start_at` date is in the future -- the `start_at` or `end_at` overlaps another shift for the same employee -- If `Break`s are set in the request, a break `start_at` -must not be before the `Shift.start_at`. A break `end_at` must not be after -the `Shift.end_at` - -```ruby -def create_shift(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Create Shift Request Hash`](/doc/models/create-shift-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Create Shift Response Hash`](/doc/models/create-shift-response.md) - -### Example Usage - -```ruby -body = {} -body[:idempotency_key] = 'HIDSNG5KS478L' -body[:shift] = {} -body[:shift][:employee_id] = 'ormj0jJJZ5OZIzxrZYJI' -body[:shift][:location_id] = 'PAA1RJZZKXBFG' -body[:shift][:start_at] = '2019-01-25T03:11:00-05:00' -body[:shift][:end_at] = '2019-01-25T13:11:00-05:00' -body[:shift][:wage] = {} -body[:shift][:wage][:title] = 'Barista' -body[:shift][:wage][:hourly_rate] = {} -body[:shift][:wage][:hourly_rate][:amount] = 1100 -body[:shift][:wage][:hourly_rate][:currency] = 'USD' -body[:shift][:breaks] = [] - - -body[:shift][:breaks][0] = {} -body[:shift][:breaks][0][:start_at] = '2019-01-25T06:11:00-05:00' -body[:shift][:breaks][0][:end_at] = '2019-01-25T06:16:00-05:00' -body[:shift][:breaks][0][:break_type_id] = 'REGS1EQR1TPZ5' -body[:shift][:breaks][0][:name] = 'Tea Break' -body[:shift][:breaks][0][:expected_duration] = 'PT5M' -body[:shift][:breaks][0][:is_paid] = true - - -result = labor_api.create_shift(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Search Shifts - -Returns a paginated list of `Shift` records for a business. -The list to be returned can be filtered by: -- Location IDs **and** -- employee IDs **and** -- shift status (`OPEN`, `CLOSED`) **and** -- shift start **and** -- shift end **and** -- work day details - -The list can be sorted by: -- `start_at` -- `end_at` -- `created_at` -- `updated_at` - -```ruby -def search_shifts(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Search Shifts Request Hash`](/doc/models/search-shifts-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Search Shifts Response Hash`](/doc/models/search-shifts-response.md) - -### Example Usage - -```ruby -body = {} -body[:query] = {} -body[:query][:filter] = {} -body[:query][:filter][:workday] = {} -body[:query][:filter][:workday][:date_range] = {} -body[:query][:filter][:workday][:date_range][:start_date] = '2019-01-20' -body[:query][:filter][:workday][:date_range][:end_date] = '2019-02-03' -body[:query][:filter][:workday][:match_shifts_by] = 'START_AT' -body[:query][:filter][:workday][:default_timezone] = 'America/Los_Angeles' -body[:limit] = 100 - -result = labor_api.search_shifts(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Shift - -Deletes a `Shift`. - -```ruby -def delete_shift(id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Template, Required | UUID for the `Shift` being deleted. | - -### Response Type - -[`Delete Shift Response Hash`](/doc/models/delete-shift-response.md) - -### Example Usage - -```ruby -id = 'id0' - -result = labor_api.delete_shift(id: id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Get Shift - -Returns a single `Shift` specified by id. - -```ruby -def get_shift(id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Template, Required | UUID for the `Shift` being retrieved. | - -### Response Type - -[`Get Shift Response Hash`](/doc/models/get-shift-response.md) - -### Example Usage - -```ruby -id = 'id0' - -result = labor_api.get_shift(id: id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Shift - -Updates an existing `Shift`. - -When adding a `Break` to a `Shift`, any earlier `Breaks` in the `Shift` have -the `end_at` property set to a valid RFC-3339 datetime string. - -When closing a `Shift`, all `Break` instances in the shift must be complete with `end_at` -set on each `Break`. - -```ruby -def update_shift(id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Template, Required | ID of the object being updated. | -| `body` | [`Update Shift Request Hash`](/doc/models/update-shift-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Update Shift Response Hash`](/doc/models/update-shift-response.md) - -### Example Usage - -```ruby -id = 'id0' -body = {} -body[:shift] = {} -body[:shift][:employee_id] = 'ormj0jJJZ5OZIzxrZYJI' -body[:shift][:location_id] = 'PAA1RJZZKXBFG' -body[:shift][:start_at] = '2019-01-25T03:11:00-05:00' -body[:shift][:end_at] = '2019-01-25T13:11:00-05:00' -body[:shift][:wage] = {} -body[:shift][:wage][:title] = 'Bartender' -body[:shift][:wage][:hourly_rate] = {} -body[:shift][:wage][:hourly_rate][:amount] = 1500 -body[:shift][:wage][:hourly_rate][:currency] = 'USD' -body[:shift][:breaks] = [] - - -body[:shift][:breaks][0] = {} -body[:shift][:breaks][0][:id] = 'X7GAQYVVRRG6P' -body[:shift][:breaks][0][:start_at] = '2019-01-25T06:11:00-05:00' -body[:shift][:breaks][0][:end_at] = '2019-01-25T06:16:00-05:00' -body[:shift][:breaks][0][:break_type_id] = 'REGS1EQR1TPZ5' -body[:shift][:breaks][0][:name] = 'Tea Break' -body[:shift][:breaks][0][:expected_duration] = 'PT5M' -body[:shift][:breaks][0][:is_paid] = true - -body[:shift][:version] = 1 - -result = labor_api.update_shift(id: id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Workweek Configs - -Returns a list of `WorkweekConfig` instances for a business. - -```ruby -def list_workweek_configs(limit: nil, - cursor: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `limit` | `Integer` | Query, Optional | Maximum number of Workweek Configs to return per page. | -| `cursor` | `String` | Query, Optional | Pointer to the next page of Workweek Config results to fetch. | - -### Response Type - -[`List Workweek Configs Response Hash`](/doc/models/list-workweek-configs-response.md) - -### Example Usage - -```ruby -result = labor_api.list_workweek_configs() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Workweek Config - -Updates a `WorkweekConfig`. - -```ruby -def update_workweek_config(id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Template, Required | UUID for the `WorkweekConfig` object being updated. | -| `body` | [`Update Workweek Config Request Hash`](/doc/models/update-workweek-config-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Update Workweek Config Response Hash`](/doc/models/update-workweek-config-response.md) - -### Example Usage - -```ruby -id = 'id0' -body = {} -body[:workweek_config] = {} -body[:workweek_config][:start_of_week] = 'MON' -body[:workweek_config][:start_of_day_local_time] = '10:00' -body[:workweek_config][:version] = 10 - -result = labor_api.update_workweek_config(id: id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Labor + +```ruby +labor_api = client.labor +``` + +## Class Name + +`LaborApi` + +## Methods + +* [List Break Types](/doc/labor.md#list-break-types) +* [Create Break Type](/doc/labor.md#create-break-type) +* [Delete Break Type](/doc/labor.md#delete-break-type) +* [Get Break Type](/doc/labor.md#get-break-type) +* [Update Break Type](/doc/labor.md#update-break-type) +* [List Employee Wages](/doc/labor.md#list-employee-wages) +* [Get Employee Wage](/doc/labor.md#get-employee-wage) +* [Create Shift](/doc/labor.md#create-shift) +* [Search Shifts](/doc/labor.md#search-shifts) +* [Delete Shift](/doc/labor.md#delete-shift) +* [Get Shift](/doc/labor.md#get-shift) +* [Update Shift](/doc/labor.md#update-shift) +* [List Workweek Configs](/doc/labor.md#list-workweek-configs) +* [Update Workweek Config](/doc/labor.md#update-workweek-config) + +## List Break Types + +Returns a paginated list of `BreakType` instances for a business. + +```ruby +def list_break_types(location_id: nil, + limit: nil, + cursor: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Query, Optional | Filter Break Types returned to only those that are associated with the
specified location. | +| `limit` | `Integer` | Query, Optional | Maximum number of Break Types to return per page. Can range between 1
and 200. The default is the maximum at 200. | +| `cursor` | `String` | Query, Optional | Pointer to the next page of Break Type results to fetch. | + +### Response Type + +[`List Break Types Response Hash`](/doc/models/list-break-types-response.md) + +### Example Usage + +```ruby +result = labor_api.list_break_types() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Break Type + +Creates a new `BreakType`. + +A `BreakType` is a template for creating `Break` objects. +You must provide the following values in your request to this +endpoint: + +- `location_id` +- `break_name` +- `expected_duration` +- `is_paid` + +You can only have 3 `BreakType` instances per location. If you attempt to add a 4th +`BreakType` for a location, an `INVALID_REQUEST_ERROR` "Exceeded limit of 3 breaks per location." +is returned. + +```ruby +def create_break_type(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Create Break Type Request Hash`](/doc/models/create-break-type-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Create Break Type Response Hash`](/doc/models/create-break-type-response.md) + +### Example Usage + +```ruby +body = {} +body[:idempotency_key] = 'PAD3NG5KSN2GL' +body[:break_type] = {} +body[:break_type][:location_id] = 'CGJN03P1D08GF' +body[:break_type][:break_name] = 'Lunch Break' +body[:break_type][:expected_duration] = 'PT30M' +body[:break_type][:is_paid] = true + +result = labor_api.create_break_type(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Break Type + +Deletes an existing `BreakType`. + +A `BreakType` can be deleted even if it is referenced from a `Shift`. + +```ruby +def delete_break_type(id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Template, Required | UUID for the `BreakType` being deleted. | + +### Response Type + +[`Delete Break Type Response Hash`](/doc/models/delete-break-type-response.md) + +### Example Usage + +```ruby +id = 'id0' + +result = labor_api.delete_break_type(id: id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Get Break Type + +Returns a single `BreakType` specified by id. + +```ruby +def get_break_type(id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Template, Required | UUID for the `BreakType` being retrieved. | + +### Response Type + +[`Get Break Type Response Hash`](/doc/models/get-break-type-response.md) + +### Example Usage + +```ruby +id = 'id0' + +result = labor_api.get_break_type(id: id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Break Type + +Updates an existing `BreakType`. + +```ruby +def update_break_type(id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Template, Required | UUID for the `BreakType` being updated. | +| `body` | [`Update Break Type Request Hash`](/doc/models/update-break-type-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Update Break Type Response Hash`](/doc/models/update-break-type-response.md) + +### Example Usage + +```ruby +id = 'id0' +body = {} +body[:break_type] = {} +body[:break_type][:location_id] = '26M7H24AZ9N6R' +body[:break_type][:break_name] = 'Lunch' +body[:break_type][:expected_duration] = 'PT50M' +body[:break_type][:is_paid] = true +body[:break_type][:version] = 1 + +result = labor_api.update_break_type(id: id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Employee Wages + +Returns a paginated list of `EmployeeWage` instances for a business. + +```ruby +def list_employee_wages(employee_id: nil, + limit: nil, + cursor: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `employee_id` | `String` | Query, Optional | Filter wages returned to only those that are associated with the
specified employee. | +| `limit` | `Integer` | Query, Optional | Maximum number of Employee Wages to return per page. Can range between
1 and 200. The default is the maximum at 200. | +| `cursor` | `String` | Query, Optional | Pointer to the next page of Employee Wage results to fetch. | + +### Response Type + +[`List Employee Wages Response Hash`](/doc/models/list-employee-wages-response.md) + +### Example Usage + +```ruby +result = labor_api.list_employee_wages() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Get Employee Wage + +Returns a single `EmployeeWage` specified by id. + +```ruby +def get_employee_wage(id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Template, Required | UUID for the `EmployeeWage` being retrieved. | + +### Response Type + +[`Get Employee Wage Response Hash`](/doc/models/get-employee-wage-response.md) + +### Example Usage + +```ruby +id = 'id0' + +result = labor_api.get_employee_wage(id: id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Shift + +Creates a new `Shift`. + +A `Shift` represents a complete work day for a single employee. +You must provide the following values in your request to this +endpoint: + +- `location_id` +- `employee_id` +- `start_at` + +An attempt to create a new `Shift` can result in a `BAD_REQUEST` error when: +- The `status` of the new `Shift` is `OPEN` and the employee has another +shift with an `OPEN` status. +- The `start_at` date is in the future +- the `start_at` or `end_at` overlaps another shift for the same employee +- If `Break`s are set in the request, a break `start_at` +must not be before the `Shift.start_at`. A break `end_at` must not be after +the `Shift.end_at` + +```ruby +def create_shift(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Create Shift Request Hash`](/doc/models/create-shift-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Create Shift Response Hash`](/doc/models/create-shift-response.md) + +### Example Usage + +```ruby +body = {} +body[:idempotency_key] = 'HIDSNG5KS478L' +body[:shift] = {} +body[:shift][:employee_id] = 'ormj0jJJZ5OZIzxrZYJI' +body[:shift][:location_id] = 'PAA1RJZZKXBFG' +body[:shift][:start_at] = '2019-01-25T03:11:00-05:00' +body[:shift][:end_at] = '2019-01-25T13:11:00-05:00' +body[:shift][:wage] = {} +body[:shift][:wage][:title] = 'Barista' +body[:shift][:wage][:hourly_rate] = {} +body[:shift][:wage][:hourly_rate][:amount] = 1100 +body[:shift][:wage][:hourly_rate][:currency] = 'USD' +body[:shift][:breaks] = [] + + +body[:shift][:breaks][0] = {} +body[:shift][:breaks][0][:start_at] = '2019-01-25T06:11:00-05:00' +body[:shift][:breaks][0][:end_at] = '2019-01-25T06:16:00-05:00' +body[:shift][:breaks][0][:break_type_id] = 'REGS1EQR1TPZ5' +body[:shift][:breaks][0][:name] = 'Tea Break' +body[:shift][:breaks][0][:expected_duration] = 'PT5M' +body[:shift][:breaks][0][:is_paid] = true + + +result = labor_api.create_shift(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Search Shifts + +Returns a paginated list of `Shift` records for a business. +The list to be returned can be filtered by: +- Location IDs **and** +- employee IDs **and** +- shift status (`OPEN`, `CLOSED`) **and** +- shift start **and** +- shift end **and** +- work day details + +The list can be sorted by: +- `start_at` +- `end_at` +- `created_at` +- `updated_at` + +```ruby +def search_shifts(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Search Shifts Request Hash`](/doc/models/search-shifts-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Search Shifts Response Hash`](/doc/models/search-shifts-response.md) + +### Example Usage + +```ruby +body = {} +body[:query] = {} +body[:query][:filter] = {} +body[:query][:filter][:workday] = {} +body[:query][:filter][:workday][:date_range] = {} +body[:query][:filter][:workday][:date_range][:start_date] = '2019-01-20' +body[:query][:filter][:workday][:date_range][:end_date] = '2019-02-03' +body[:query][:filter][:workday][:match_shifts_by] = 'START_AT' +body[:query][:filter][:workday][:default_timezone] = 'America/Los_Angeles' +body[:limit] = 100 + +result = labor_api.search_shifts(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Shift + +Deletes a `Shift`. + +```ruby +def delete_shift(id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Template, Required | UUID for the `Shift` being deleted. | + +### Response Type + +[`Delete Shift Response Hash`](/doc/models/delete-shift-response.md) + +### Example Usage + +```ruby +id = 'id0' + +result = labor_api.delete_shift(id: id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Get Shift + +Returns a single `Shift` specified by id. + +```ruby +def get_shift(id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Template, Required | UUID for the `Shift` being retrieved. | + +### Response Type + +[`Get Shift Response Hash`](/doc/models/get-shift-response.md) + +### Example Usage + +```ruby +id = 'id0' + +result = labor_api.get_shift(id: id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Shift + +Updates an existing `Shift`. + +When adding a `Break` to a `Shift`, any earlier `Breaks` in the `Shift` have +the `end_at` property set to a valid RFC-3339 datetime string. + +When closing a `Shift`, all `Break` instances in the shift must be complete with `end_at` +set on each `Break`. + +```ruby +def update_shift(id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Template, Required | ID of the object being updated. | +| `body` | [`Update Shift Request Hash`](/doc/models/update-shift-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Update Shift Response Hash`](/doc/models/update-shift-response.md) + +### Example Usage + +```ruby +id = 'id0' +body = {} +body[:shift] = {} +body[:shift][:employee_id] = 'ormj0jJJZ5OZIzxrZYJI' +body[:shift][:location_id] = 'PAA1RJZZKXBFG' +body[:shift][:start_at] = '2019-01-25T03:11:00-05:00' +body[:shift][:end_at] = '2019-01-25T13:11:00-05:00' +body[:shift][:wage] = {} +body[:shift][:wage][:title] = 'Bartender' +body[:shift][:wage][:hourly_rate] = {} +body[:shift][:wage][:hourly_rate][:amount] = 1500 +body[:shift][:wage][:hourly_rate][:currency] = 'USD' +body[:shift][:breaks] = [] + + +body[:shift][:breaks][0] = {} +body[:shift][:breaks][0][:id] = 'X7GAQYVVRRG6P' +body[:shift][:breaks][0][:start_at] = '2019-01-25T06:11:00-05:00' +body[:shift][:breaks][0][:end_at] = '2019-01-25T06:16:00-05:00' +body[:shift][:breaks][0][:break_type_id] = 'REGS1EQR1TPZ5' +body[:shift][:breaks][0][:name] = 'Tea Break' +body[:shift][:breaks][0][:expected_duration] = 'PT5M' +body[:shift][:breaks][0][:is_paid] = true + +body[:shift][:version] = 1 + +result = labor_api.update_shift(id: id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Workweek Configs + +Returns a list of `WorkweekConfig` instances for a business. + +```ruby +def list_workweek_configs(limit: nil, + cursor: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `limit` | `Integer` | Query, Optional | Maximum number of Workweek Configs to return per page. | +| `cursor` | `String` | Query, Optional | Pointer to the next page of Workweek Config results to fetch. | + +### Response Type + +[`List Workweek Configs Response Hash`](/doc/models/list-workweek-configs-response.md) + +### Example Usage + +```ruby +result = labor_api.list_workweek_configs() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Workweek Config + +Updates a `WorkweekConfig`. + +```ruby +def update_workweek_config(id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Template, Required | UUID for the `WorkweekConfig` object being updated. | +| `body` | [`Update Workweek Config Request Hash`](/doc/models/update-workweek-config-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Update Workweek Config Response Hash`](/doc/models/update-workweek-config-response.md) + +### Example Usage + +```ruby +id = 'id0' +body = {} +body[:workweek_config] = {} +body[:workweek_config][:start_of_week] = 'MON' +body[:workweek_config][:start_of_day_local_time] = '10:00' +body[:workweek_config][:version] = 10 + +result = labor_api.update_workweek_config(id: id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/locations.md b/doc/locations.md index 2776bc80..87276f1f 100644 --- a/doc/locations.md +++ b/doc/locations.md @@ -1,38 +1,111 @@ -# Locations - -```ruby -locations_api = client.locations -``` - -## Class Name - -`LocationsApi` - -## List Locations - -Provides the details for all of a business's locations. - -Most other Connect API endpoints have a required `location_id` path parameter. -The `id` field of the [`Location`](#type-location) objects returned by this -endpoint correspond to that `location_id` parameter. - -```ruby -def list_locations -``` - -### Response Type - -[`List Locations Response Hash`](/doc/models/list-locations-response.md) - -### Example Usage - -```ruby -result = locations_api.list_locations() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Locations + +```ruby +locations_api = client.locations +``` + +## Class Name + +`LocationsApi` + +## Methods + +* [List Locations](/doc/locations.md#list-locations) +* [Retrieve Location](/doc/locations.md#retrieve-location) +* [Update Location](/doc/locations.md#update-location) + +## List Locations + +Provides the details for all of a business's locations. + +Most other Connect API endpoints have a required `location_id` path parameter. +The `id` field of the [`Location`](#type-location) objects returned by this +endpoint correspond to that `location_id` parameter. + +```ruby +def list_locations +``` + +### Response Type + +[`List Locations Response Hash`](/doc/models/list-locations-response.md) + +### Example Usage + +```ruby +result = locations_api.list_locations() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Location + +Retrieves details of a location. + +```ruby +def retrieve_location(location_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to retrieve. | + +### Response Type + +[`Retrieve Location Response Hash`](/doc/models/retrieve-location-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = locations_api.retrieve_location(location_id: location_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Location + +Updates the `Location` specified by the given ID. + +```ruby +def update_location(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to update. | +| `body` | [`Update Location Request Hash`](/doc/models/update-location-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Update Location Response Hash`](/doc/models/update-location-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} + +result = locations_api.update_location(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/merchants.md b/doc/merchants.md new file mode 100644 index 00000000..345e5209 --- /dev/null +++ b/doc/merchants.md @@ -0,0 +1,42 @@ +# Merchants + +```ruby +merchants_api = client.merchants +``` + +## Class Name + +`MerchantsApi` + +## Retrieve Merchant + +Retrieve a `Merchant` object for the given `merchant_id`. + +```ruby +def retrieve_merchant(merchant_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `merchant_id` | `String` | Template, Required | The ID of the merchant to retrieve | + +### Response Type + +[`Retrieve Merchant Response Hash`](/doc/models/retrieve-merchant-response.md) + +### Example Usage + +```ruby +merchant_id = 'merchant_id0' + +result = merchants_api.retrieve_merchant(merchant_id: merchant_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/mobile-authorization.md b/doc/mobile-authorization.md index 528e3bdb..c2fd12a2 100644 --- a/doc/mobile-authorization.md +++ b/doc/mobile-authorization.md @@ -1,53 +1,53 @@ -# Mobile Authorization - -```ruby -mobile_authorization_api = client.mobile_authorization -``` - -## Class Name - -`MobileAuthorizationApi` - -## Create Mobile Authorization Code - -Generates code to authorize a mobile application to connect to a Square card reader - -Authorization codes are one-time-use and expire __60 minutes__ after being issued. - -__Important:__ The `Authorization` header you provide to this endpoint must have the following format: - -``` -Authorization: Bearer ACCESS_TOKEN -``` - -Replace `ACCESS_TOKEN` with a [valid production authorization credential](https://docs.connect.squareup.com/get-started#step-4-understand-the-different-application-credentials). - -```ruby -def create_mobile_authorization_code(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Create Mobile Authorization Code Request Hash`](/doc/models/create-mobile-authorization-code-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Create Mobile Authorization Code Response Hash`](/doc/models/create-mobile-authorization-code-response.md) - -### Example Usage - -```ruby -body = {} -body[:location_id] = 'YOUR_LOCATION_ID' - -result = mobile_authorization_api.create_mobile_authorization_code(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Mobile Authorization + +```ruby +mobile_authorization_api = client.mobile_authorization +``` + +## Class Name + +`MobileAuthorizationApi` + +## Create Mobile Authorization Code + +Generates code to authorize a mobile application to connect to a Square card reader + +Authorization codes are one-time-use and expire __60 minutes__ after being issued. + +__Important:__ The `Authorization` header you provide to this endpoint must have the following format: + +``` +Authorization: Bearer ACCESS_TOKEN +``` + +Replace `ACCESS_TOKEN` with a [valid production authorization credential](https://developer.squareup.com/docs/get-started#step-4-understand-the-different-application-credentials). + +```ruby +def create_mobile_authorization_code(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Create Mobile Authorization Code Request Hash`](/doc/models/create-mobile-authorization-code-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Create Mobile Authorization Code Response Hash`](/doc/models/create-mobile-authorization-code-response.md) + +### Example Usage + +```ruby +body = {} +body[:location_id] = 'YOUR_LOCATION_ID' + +result = mobile_authorization_api.create_mobile_authorization_code(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/models/additional-recipient-receivable-refund.md b/doc/models/additional-recipient-receivable-refund.md index 40838881..ca631749 100644 --- a/doc/models/additional-recipient-receivable-refund.md +++ b/doc/models/additional-recipient-receivable-refund.md @@ -1,35 +1,35 @@ -## Additional Recipient Receivable Refund - -A refund of an [AdditionalRecipientReceivable](./models/additional-recipient-receivable.md). This includes the ID of the additional recipient receivable associated to this object, as well as a reference to the [Refund](./models/refund.md) that created this receivable refund. - -### Structure - -`AdditionalRecipientReceivableRefund` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | | The receivable refund's unique ID, issued by Square payments servers. | -| `receivable_id` | `String` | | The ID of the receivable that the refund was applied to. | -| `refund_id` | `String` | | The ID of the refund that is associated to this receivable refund. | -| `transaction_location_id` | `String` | | The ID of the location that created the receivable. This is the location ID on the associated transaction. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `created_at` | `String` | Optional | The time when the refund was created, in RFC 3339 format. | - -### Example (as JSON) - -```json -{ - "id": "id0", - "receivable_id": "receivable_id0", - "refund_id": "refund_id4", - "transaction_location_id": "transaction_location_id6", - "amount_money": { - "amount": null, - "currency": null - }, - "created_at": null -} -``` - +## Additional Recipient Receivable Refund + +A refund of an [AdditionalRecipientReceivable](#type-additionalrecipientreceivable). This includes the ID of the additional recipient receivable associated to this object, as well as a reference to the [Refund](#type-refund) that created this receivable refund. + +### Structure + +`AdditionalRecipientReceivableRefund` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | | The receivable refund's unique ID, issued by Square payments servers. | +| `receivable_id` | `String` | | The ID of the receivable that the refund was applied to. | +| `refund_id` | `String` | | The ID of the refund that is associated to this receivable refund. | +| `transaction_location_id` | `String` | | The ID of the location that created the receivable. This is the location ID on the associated transaction. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `created_at` | `String` | Optional | The time when the refund was created, in RFC 3339 format. | + +### Example (as JSON) + +```json +{ + "id": "id0", + "receivable_id": "receivable_id0", + "refund_id": "refund_id4", + "transaction_location_id": "transaction_location_id6", + "amount_money": { + "amount": null, + "currency": null + }, + "created_at": null +} +``` + diff --git a/doc/models/additional-recipient-receivable.md b/doc/models/additional-recipient-receivable.md index 275cbcf7..20b4d635 100644 --- a/doc/models/additional-recipient-receivable.md +++ b/doc/models/additional-recipient-receivable.md @@ -1,35 +1,35 @@ -## Additional Recipient Receivable - -Represents a monetary distribution of part of a [Transaction](./models/transaction.md)'s amount for Transactions which included additional recipients. The location of this receivable is that same as the one specified in the [AdditionalRecipient](./models/additional-recipient.md). - -### Structure - -`AdditionalRecipientReceivable` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | | The additional recipient receivable's unique ID, issued by Square payments servers. | -| `transaction_id` | `String` | | The ID of the transaction that the additional recipient receivable was applied to. | -| `transaction_location_id` | `String` | | The ID of the location that created the receivable. This is the location ID on the associated transaction. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `created_at` | `String` | Optional | The time when the additional recipient receivable was created, in RFC 3339 format. | -| `refunds` | [`Array`](/doc/models/additional-recipient-receivable-refund.md) | Optional | Any refunds of the receivable that have been applied. | - -### Example (as JSON) - -```json -{ - "id": "id0", - "transaction_id": "transaction_id8", - "transaction_location_id": "transaction_location_id6", - "amount_money": { - "amount": null, - "currency": null - }, - "created_at": null, - "refunds": null -} -``` - +## Additional Recipient Receivable + +Represents a monetary distribution of part of a [Transaction](#type-transaction)'s amount for Transactions which included additional recipients. The location of this receivable is that same as the one specified in the [AdditionalRecipient](#type-additionalrecipient). + +### Structure + +`AdditionalRecipientReceivable` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | | The additional recipient receivable's unique ID, issued by Square payments servers. | +| `transaction_id` | `String` | | The ID of the transaction that the additional recipient receivable was applied to. | +| `transaction_location_id` | `String` | | The ID of the location that created the receivable. This is the location ID on the associated transaction. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `created_at` | `String` | Optional | The time when the additional recipient receivable was created, in RFC 3339 format. | +| `refunds` | [`Array`](/doc/models/additional-recipient-receivable-refund.md) | Optional | Any refunds of the receivable that have been applied. | + +### Example (as JSON) + +```json +{ + "id": "id0", + "transaction_id": "transaction_id8", + "transaction_location_id": "transaction_location_id6", + "amount_money": { + "amount": null, + "currency": null + }, + "created_at": null, + "refunds": null +} +``` + diff --git a/doc/models/additional-recipient.md b/doc/models/additional-recipient.md index a5aebca2..5ba5c92b 100644 --- a/doc/models/additional-recipient.md +++ b/doc/models/additional-recipient.md @@ -1,31 +1,31 @@ -## Additional Recipient - -Represents an additional recipient (other than the merchant) receiving a portion of this tender. - -### Structure - -`AdditionalRecipient` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | | The location ID for a recipient (other than the merchant) receiving a portion of this tender. | -| `description` | `String` | | The description of the additional recipient. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `receivable_id` | `String` | Optional | The unique ID for this [AdditionalRecipientReceivable](./models/additional-recipient-receivable.md), assigned by the server. | - -### Example (as JSON) - -```json -{ - "location_id": "location_id4", - "description": "description0", - "amount_money": { - "amount": null, - "currency": null - }, - "receivable_id": null -} -``` - +## Additional Recipient + +Represents an additional recipient (other than the merchant) receiving a portion of this tender. + +### Structure + +`AdditionalRecipient` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | | The location ID for a recipient (other than the merchant) receiving a portion of this tender. | +| `description` | `String` | | The description of the additional recipient. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `receivable_id` | `String` | Optional | The unique ID for this [AdditionalRecipientReceivable](#type-additionalrecipientreceivable), assigned by the server. | + +### Example (as JSON) + +```json +{ + "location_id": "location_id4", + "description": "description0", + "amount_money": { + "amount": null, + "currency": null + }, + "receivable_id": null +} +``` + diff --git a/doc/models/address.md b/doc/models/address.md index 6f1bcb14..3b066e55 100644 --- a/doc/models/address.md +++ b/doc/models/address.md @@ -1,50 +1,50 @@ -## Address - -Represents a physical address. - -### Structure - -`Address` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `address_line_1` | `String` | Optional | The first line of the address.

Fields that start with `address_line` provide the address's most specific
details, like street number, street name, and building name. They do *not*
provide less specific details like city, state/province, or country (these
details are provided in other fields). | -| `address_line_2` | `String` | Optional | The second line of the address, if any. | -| `address_line_3` | `String` | Optional | The third line of the address, if any. | -| `locality` | `String` | Optional | The city or town of the address. | -| `sublocality` | `String` | Optional | A civil region within the address's `locality`, if any. | -| `sublocality_2` | `String` | Optional | A civil region within the address's `sublocality`, if any. | -| `sublocality_3` | `String` | Optional | A civil region within the address's `sublocality_2`, if any. | -| `administrative_district_level_1` | `String` | Optional | A civil entity within the address's country. In the US, this
is the state. | -| `administrative_district_level_2` | `String` | Optional | A civil entity within the address's `administrative_district_level_1`.
In the US, this is the county. | -| `administrative_district_level_3` | `String` | Optional | A civil entity within the address's `administrative_district_level_2`,
if any. | -| `postal_code` | `String` | Optional | The address's postal code. | -| `country` | [`String (Country)`](/doc/models/country.md) | Optional | Indicates the country associated with another entity, such as a business.
Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). | -| `first_name` | `String` | Optional | Optional first name when it's representing recipient. | -| `last_name` | `String` | Optional | Optional last name when it's representing recipient. | -| `organization` | `String` | Optional | Optional organization name when it's representing recipient. | - -### Example (as JSON) - -```json -{ - "address_line_1": null, - "address_line_2": null, - "address_line_3": null, - "locality": null, - "sublocality": null, - "sublocality_2": null, - "sublocality_3": null, - "administrative_district_level_1": null, - "administrative_district_level_2": null, - "administrative_district_level_3": null, - "postal_code": null, - "country": null, - "first_name": null, - "last_name": null, - "organization": null -} -``` - +## Address + +Represents a physical address. + +### Structure + +`Address` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `address_line_1` | `String` | Optional | The first line of the address.

Fields that start with `address_line` provide the address's most specific
details, like street number, street name, and building name. They do *not*
provide less specific details like city, state/province, or country (these
details are provided in other fields). | +| `address_line_2` | `String` | Optional | The second line of the address, if any. | +| `address_line_3` | `String` | Optional | The third line of the address, if any. | +| `locality` | `String` | Optional | The city or town of the address. | +| `sublocality` | `String` | Optional | A civil region within the address's `locality`, if any. | +| `sublocality_2` | `String` | Optional | A civil region within the address's `sublocality`, if any. | +| `sublocality_3` | `String` | Optional | A civil region within the address's `sublocality_2`, if any. | +| `administrative_district_level_1` | `String` | Optional | A civil entity within the address's country. In the US, this
is the state. | +| `administrative_district_level_2` | `String` | Optional | A civil entity within the address's `administrative_district_level_1`.
In the US, this is the county. | +| `administrative_district_level_3` | `String` | Optional | A civil entity within the address's `administrative_district_level_2`,
if any. | +| `postal_code` | `String` | Optional | The address's postal code. | +| `country` | [`String (Country)`](/doc/models/country.md) | Optional | Indicates the country associated with another entity, such as a business.
Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). | +| `first_name` | `String` | Optional | Optional first name when it's representing recipient. | +| `last_name` | `String` | Optional | Optional last name when it's representing recipient. | +| `organization` | `String` | Optional | Optional organization name when it's representing recipient. | + +### Example (as JSON) + +```json +{ + "address_line_1": null, + "address_line_2": null, + "address_line_3": null, + "locality": null, + "sublocality": null, + "sublocality_2": null, + "sublocality_3": null, + "administrative_district_level_1": null, + "administrative_district_level_2": null, + "administrative_district_level_3": null, + "postal_code": null, + "country": null, + "first_name": null, + "last_name": null, + "organization": null +} +``` + diff --git a/doc/models/balance-payment-details.md b/doc/models/balance-payment-details.md index a3ead1c8..9daccb69 100644 --- a/doc/models/balance-payment-details.md +++ b/doc/models/balance-payment-details.md @@ -1,24 +1,24 @@ -## Balance Payment Details - -Reflects the current status of a balance payment. - -### Structure - -`BalancePaymentDetails` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `account_id` | `String` | Optional | ID for the account used to fund the payment. | -| `status` | `String` | Optional | The balance payment’s current state. Can be `COMPLETED` or `FAILED`. | - -### Example (as JSON) - -```json -{ - "account_id": null, - "status": null -} -``` - +## Balance Payment Details + +Reflects the current status of a balance payment. + +### Structure + +`BalancePaymentDetails` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `account_id` | `String` | Optional | ID for the account used to fund the payment. | +| `status` | `String` | Optional | The balance payment’s current state. Can be `COMPLETED` or `FAILED`. | + +### Example (as JSON) + +```json +{ + "account_id": null, + "status": null +} +``` + diff --git a/doc/models/batch-change-inventory-request.md b/doc/models/batch-change-inventory-request.md index 38278e0f..f84702d8 100644 --- a/doc/models/batch-change-inventory-request.md +++ b/doc/models/batch-change-inventory-request.md @@ -1,37 +1,37 @@ -## Batch Change Inventory Request - -### Structure - -`BatchChangeInventoryRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `idempotency_key` | `String` | Optional | A client-supplied, universally unique identifier (UUID) for the
request.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) in the
[API Development 101](https://developer.squareup.com/docs/basics/api101/overview) section for more
information. | -| `changes` | [`Array`](/doc/models/inventory-change.md) | Optional | The set of physical counts and inventory adjustments to be made.
Changes are applied based on the client-supplied timestamp and may be sent
out of order. Max size is 100 changes. | -| `ignore_unchanged_counts` | `Boolean` | Optional | Indicates whether the current physical count should be ignored if
the quantity is unchanged since the last physical count. Default: `true`. | - -### Example (as JSON) - -```json -{ - "idempotency_key": "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe", - "changes": [ - { - "type": "PHYSICAL_COUNT", - "physical_count": { - "reference_id": "1536bfbf-efed-48bf-b17d-a197141b2a92", - "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", - "state": "IN_STOCK", - "location_id": "C6W5YS5QM06F5", - "quantity": "53", - "employee_id": "LRK57NSQ5X7PUD05", - "occurred_at": "2016-11-16T22:25:24.878Z" - } - } - ], - "ignore_unchanged_counts": true -} -``` - +## Batch Change Inventory Request + +### Structure + +`BatchChangeInventoryRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `String` | Optional | A client-supplied, universally unique identifier (UUID) for the
request.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) in the
[API Development 101](https://developer.squareup.com/docs/basics/api101/overview) section for more
information. | +| `changes` | [`Array`](/doc/models/inventory-change.md) | Optional | The set of physical counts and inventory adjustments to be made.
Changes are applied based on the client-supplied timestamp and may be sent
out of order. Max size is 100 changes. | +| `ignore_unchanged_counts` | `Boolean` | Optional | Indicates whether the current physical count should be ignored if
the quantity is unchanged since the last physical count. Default: `true`. | + +### Example (as JSON) + +```json +{ + "idempotency_key": "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe", + "changes": [ + { + "type": "PHYSICAL_COUNT", + "physical_count": { + "reference_id": "1536bfbf-efed-48bf-b17d-a197141b2a92", + "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", + "state": "IN_STOCK", + "location_id": "C6W5YS5QM06F5", + "quantity": "53", + "employee_id": "LRK57NSQ5X7PUD05", + "occurred_at": "2016-11-16T22:25:24.878Z" + } + } + ], + "ignore_unchanged_counts": true +} +``` + diff --git a/doc/models/batch-change-inventory-response.md b/doc/models/batch-change-inventory-response.md index cf1e5c5a..fa336217 100644 --- a/doc/models/batch-change-inventory-response.md +++ b/doc/models/batch-change-inventory-response.md @@ -1,31 +1,31 @@ -## Batch Change Inventory Response - -### Structure - -`BatchChangeInventoryResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `counts` | [`Array`](/doc/models/inventory-count.md) | Optional | The current counts for all objects referenced in the request. | - -### Example (as JSON) - -```json -{ - "errors": [], - "counts": [ - { - "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", - "catalog_object_type": "ITEM_VARIATION", - "state": "IN_STOCK", - "location_id": "C6W5YS5QM06F5", - "quantity": "53", - "calculated_at": "2016-11-16T22:28:01.223Z" - } - ] -} -``` - +## Batch Change Inventory Response + +### Structure + +`BatchChangeInventoryResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `counts` | [`Array`](/doc/models/inventory-count.md) | Optional | The current counts for all objects referenced in the request. | + +### Example (as JSON) + +```json +{ + "errors": [], + "counts": [ + { + "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", + "catalog_object_type": "ITEM_VARIATION", + "state": "IN_STOCK", + "location_id": "C6W5YS5QM06F5", + "quantity": "53", + "calculated_at": "2016-11-16T22:28:01.223Z" + } + ] +} +``` + diff --git a/doc/models/batch-delete-catalog-objects-request.md b/doc/models/batch-delete-catalog-objects-request.md index 936b4edd..4f5dc9c6 100644 --- a/doc/models/batch-delete-catalog-objects-request.md +++ b/doc/models/batch-delete-catalog-objects-request.md @@ -1,23 +1,23 @@ -## Batch Delete Catalog Objects Request - -### Structure - -`BatchDeleteCatalogObjectsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `object_ids` | `Array` | Optional | The IDs of the [CatalogObject](./models/catalog-object.md)s to be deleted. When an object is deleted, other objects
in the graph that depend on that object will be deleted as well (for example, deleting a
[CatalogItem](./models/catalog-item.md) will delete its [CatalogItemVariation](./models/catalog-item-variation.md)s). | - -### Example (as JSON) - -```json -{ - "object_ids": [ - "W62UWFY35CWMYGVWK6TWJDNI", - "AA27W3M2GGTF3H6AVPNB77CK" - ] -} -``` - +## Batch Delete Catalog Objects Request + +### Structure + +`BatchDeleteCatalogObjectsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `object_ids` | `Array` | Optional | The IDs of the [CatalogObject](#type-catalogobject)s to be deleted. When an object is deleted, other objects
in the graph that depend on that object will be deleted as well (for example, deleting a
[CatalogItem](#type-catalogitem) will delete its [CatalogItemVariation](#type-catalogitemvariation)s). | + +### Example (as JSON) + +```json +{ + "object_ids": [ + "W62UWFY35CWMYGVWK6TWJDNI", + "AA27W3M2GGTF3H6AVPNB77CK" + ] +} +``` + diff --git a/doc/models/batch-delete-catalog-objects-response.md b/doc/models/batch-delete-catalog-objects-response.md index acb112eb..04fe9443 100644 --- a/doc/models/batch-delete-catalog-objects-response.md +++ b/doc/models/batch-delete-catalog-objects-response.md @@ -1,26 +1,26 @@ -## Batch Delete Catalog Objects Response - -### Structure - -`BatchDeleteCatalogObjectsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `deleted_object_ids` | `Array` | Optional | The IDs of all [CatalogObject](./models/catalog-object.md)s deleted by this request. | -| `deleted_at` | `String` | Optional | The database [timestamp](#workingwithdates) of this deletion in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | - -### Example (as JSON) - -```json -{ - "deleted_object_ids": [ - "W62UWFY35CWMYGVWK6TWJDNI", - "AA27W3M2GGTF3H6AVPNB77CK" - ], - "deleted_at": "2016-11-16T22:25:24.878Z" -} -``` - +## Batch Delete Catalog Objects Response + +### Structure + +`BatchDeleteCatalogObjectsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `deleted_object_ids` | `Array` | Optional | The IDs of all [CatalogObject](#type-catalogobject)s deleted by this request. | +| `deleted_at` | `String` | Optional | The database [timestamp](#workingwithdates) of this deletion in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | + +### Example (as JSON) + +```json +{ + "deleted_object_ids": [ + "W62UWFY35CWMYGVWK6TWJDNI", + "AA27W3M2GGTF3H6AVPNB77CK" + ], + "deleted_at": "2016-11-16T22:25:24.878Z" +} +``` + diff --git a/doc/models/batch-retrieve-catalog-objects-request.md b/doc/models/batch-retrieve-catalog-objects-request.md index 7a999bff..a7edacec 100644 --- a/doc/models/batch-retrieve-catalog-objects-request.md +++ b/doc/models/batch-retrieve-catalog-objects-request.md @@ -1,25 +1,25 @@ -## Batch Retrieve Catalog Objects Request - -### Structure - -`BatchRetrieveCatalogObjectsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `object_ids` | `Array` | | The IDs of the [CatalogObject](./models/catalog-object.md)s to be retrieved. | -| `include_related_objects` | `Boolean` | Optional | If `true`, the response will include additional objects that are related to the
requested objects, as follows:

If the `objects` field of the response contains a [CatalogItem](./models/catalog-item.md),
its associated [CatalogCategory](./models/catalog-category.md), [CatalogTax](./models/catalog-tax.md)es,
[CatalogImage](./models/catalog-image.md)s and [CatalogModifierList](./models/catalog-modifier-list.md)s
will be returned in the `related_objects` field of the response. If the `objects`
field of the response contains a [CatalogItemVariation](./models/catalog-item-variation.md),
its parent [CatalogItem](./models/catalog-item.md) will be returned in the `related_objects` field of
the response. | - -### Example (as JSON) - -```json -{ - "object_ids": [ - "W62UWFY35CWMYGVWK6TWJDNI", - "AA27W3M2GGTF3H6AVPNB77CK" - ], - "include_related_objects": true -} -``` - +## Batch Retrieve Catalog Objects Request + +### Structure + +`BatchRetrieveCatalogObjectsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `object_ids` | `Array` | | The IDs of the [CatalogObject](#type-catalogobject)s to be retrieved. | +| `include_related_objects` | `Boolean` | Optional | If `true`, the response will include additional objects that are related to the
requested objects, as follows:

If the `objects` field of the response contains a [CatalogItem](#type-catalogitem),
its associated [CatalogCategory](#type-catalogcategory), [CatalogTax](#type-catalogtax)es,
[CatalogImage](#type-catalogimage)s and [CatalogModifierList](#type-catalogmodifierlist)s
will be returned in the `related_objects` field of the response. If the `objects`
field of the response contains a [CatalogItemVariation](#type-catalogitemvariation),
its parent [CatalogItem](#type-catalogitem) will be returned in the `related_objects` field of
the response. | + +### Example (as JSON) + +```json +{ + "object_ids": [ + "W62UWFY35CWMYGVWK6TWJDNI", + "AA27W3M2GGTF3H6AVPNB77CK" + ], + "include_related_objects": true +} +``` + diff --git a/doc/models/batch-retrieve-catalog-objects-response.md b/doc/models/batch-retrieve-catalog-objects-response.md index 0084974a..1bd6f9ec 100644 --- a/doc/models/batch-retrieve-catalog-objects-response.md +++ b/doc/models/batch-retrieve-catalog-objects-response.md @@ -1,141 +1,141 @@ -## Batch Retrieve Catalog Objects Response - -### Structure - -`BatchRetrieveCatalogObjectsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `objects` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](./models/catalog-object.md)s returned. | -| `related_objects` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](./models/catalog-object.md)s referenced by the object in the `objects` field. | - -### Example (as JSON) - -```json -{ - "objects": [ - { - "type": "ITEM", - "id": "W62UWFY35CWMYGVWK6TWJDNI", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "item_data": { - "name": "Tea", - "description": "Hot Leaf Juice", - "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX", - "tax_ids": [ - "HURXQOOAIC4IZSI2BEXQRYFY" - ], - "variations": [ - { - "type": "ITEM_VARIATION", - "id": "2TZFAOHWGG7PAK2QEXWYPZSP", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "W62UWFY35CWMYGVWK6TWJDNI", - "name": "Mug", - "ordinal": 0, - "pricing_type": "FIXED_PRICING", - "price_money": { - "amount": 150, - "currency": "USD" - } - } - } - ] - } - }, - { - "type": "ITEM", - "id": "AA27W3M2GGTF3H6AVPNB77CK", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "item_data": { - "name": "Coffee", - "description": "Hot Bean Juice", - "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX", - "tax_ids": [ - "HURXQOOAIC4IZSI2BEXQRYFY" - ], - "variations": [ - { - "type": "ITEM_VARIATION", - "id": "LBTYIHNHU52WOIHWT7SNRIYH", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "AA27W3M2GGTF3H6AVPNB77CK", - "name": "Regular", - "ordinal": 0, - "pricing_type": "FIXED_PRICING", - "price_money": { - "amount": 250, - "currency": "USD" - } - } - }, - { - "type": "ITEM_VARIATION", - "id": "PKYIC7HGGKW5CYVSCVDEIMHY", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "AA27W3M2GGTF3H6AVPNB77CK", - "name": "Large", - "ordinal": 1, - "pricing_type": "FIXED_PRICING", - "price_money": { - "amount": 350, - "currency": "USD" - } - } - } - ] - } - } - ], - "related_objects": [ - { - "type": "CATEGORY", - "id": "BJNQCF2FJ6S6UIDT65ABHLRX", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "category_data": { - "name": "Beverages" - } - }, - { - "type": "TAX", - "id": "HURXQOOAIC4IZSI2BEXQRYFY", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "tax_data": { - "name": "Sales Tax", - "calculation_phase": "TAX_SUBTOTAL_PHASE", - "inclusion_type": "ADDITIVE", - "percentage": "5.0", - "enabled": true - } - } - ] -} -``` - +## Batch Retrieve Catalog Objects Response + +### Structure + +`BatchRetrieveCatalogObjectsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `objects` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](#type-catalogobject)s returned. | +| `related_objects` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](#type-catalogobject)s referenced by the object in the `objects` field. | + +### Example (as JSON) + +```json +{ + "objects": [ + { + "type": "ITEM", + "id": "W62UWFY35CWMYGVWK6TWJDNI", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "item_data": { + "name": "Tea", + "description": "Hot Leaf Juice", + "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX", + "tax_ids": [ + "HURXQOOAIC4IZSI2BEXQRYFY" + ], + "variations": [ + { + "type": "ITEM_VARIATION", + "id": "2TZFAOHWGG7PAK2QEXWYPZSP", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "W62UWFY35CWMYGVWK6TWJDNI", + "name": "Mug", + "ordinal": 0, + "pricing_type": "FIXED_PRICING", + "price_money": { + "amount": 150, + "currency": "USD" + } + } + } + ] + } + }, + { + "type": "ITEM", + "id": "AA27W3M2GGTF3H6AVPNB77CK", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "item_data": { + "name": "Coffee", + "description": "Hot Bean Juice", + "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX", + "tax_ids": [ + "HURXQOOAIC4IZSI2BEXQRYFY" + ], + "variations": [ + { + "type": "ITEM_VARIATION", + "id": "LBTYIHNHU52WOIHWT7SNRIYH", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "AA27W3M2GGTF3H6AVPNB77CK", + "name": "Regular", + "ordinal": 0, + "pricing_type": "FIXED_PRICING", + "price_money": { + "amount": 250, + "currency": "USD" + } + } + }, + { + "type": "ITEM_VARIATION", + "id": "PKYIC7HGGKW5CYVSCVDEIMHY", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "AA27W3M2GGTF3H6AVPNB77CK", + "name": "Large", + "ordinal": 1, + "pricing_type": "FIXED_PRICING", + "price_money": { + "amount": 350, + "currency": "USD" + } + } + } + ] + } + } + ], + "related_objects": [ + { + "type": "CATEGORY", + "id": "BJNQCF2FJ6S6UIDT65ABHLRX", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "category_data": { + "name": "Beverages" + } + }, + { + "type": "TAX", + "id": "HURXQOOAIC4IZSI2BEXQRYFY", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "tax_data": { + "name": "Sales Tax", + "calculation_phase": "TAX_SUBTOTAL_PHASE", + "inclusion_type": "ADDITIVE", + "percentage": "5.0", + "enabled": true + } + } + ] +} +``` + diff --git a/doc/models/batch-retrieve-inventory-changes-request.md b/doc/models/batch-retrieve-inventory-changes-request.md index e602ad26..04e9c78e 100644 --- a/doc/models/batch-retrieve-inventory-changes-request.md +++ b/doc/models/batch-retrieve-inventory-changes-request.md @@ -1,39 +1,39 @@ -## Batch Retrieve Inventory Changes Request - -### Structure - -`BatchRetrieveInventoryChangesRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `catalog_object_ids` | `Array` | Optional | Filters results by [CatalogObject](./models/catalog-object.md) ID.
Only applied when set. Default: unset. | -| `location_ids` | `Array` | Optional | Filters results by [Location](./models/location.md) ID. Only
applied when set. Default: unset. | -| `types` | [`Array`](/doc/models/inventory-change-type.md) | Optional | Filters results by [InventoryChangeType](./models/inventory-change-type.md).
Default: [`PHYSICAL_COUNT`, `ADJUSTMENT`]. `TRANSFER` is not supported as
a filter.
See [InventoryChangeType](./models/inventory-change-type.md) for possible values | -| `states` | [`Array`](/doc/models/inventory-state.md) | Optional | Filters `ADJUSTMENT` query results by
[InventoryState](./models/inventory-state.md). Only applied when set.
Default: unset.
See [InventoryState](./models/inventory-state.md) for possible values | -| `updated_after` | `String` | Optional | Provided as an RFC 3339 timestamp. Returns results whose
`created_at` or `calculated_at` value is after the given time.
Default: UNIX epoch (`1970-01-01T00:00:00Z`). | -| `updated_before` | `String` | Optional | Provided as an RFC 3339 timestamp. Returns results whose
`created_at` or `calculated_at` value is strictly before the given time.
Default: UNIX epoch (`1970-01-01T00:00:00Z`). | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "catalog_object_ids": [ - "W62UWFY35CWMYGVWK6TWJDNI" - ], - "location_ids": [ - "C6W5YS5QM06F5" - ], - "types": [ - "PHYSICAL_COUNT" - ], - "states": [ - "IN_STOCK" - ], - "updated_after": "2016-11-01T00:00:00.000Z", - "updated_before": "2016-12-01T00:00:00.000Z" -} -``` - +## Batch Retrieve Inventory Changes Request + +### Structure + +`BatchRetrieveInventoryChangesRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `catalog_object_ids` | `Array` | Optional | Filters results by [CatalogObject](#type-catalogobject) ID.
Only applied when set. Default: unset. | +| `location_ids` | `Array` | Optional | Filters results by [Location](#type-location) ID. Only
applied when set. Default: unset. | +| `types` | [`Array`](/doc/models/inventory-change-type.md) | Optional | Filters results by [InventoryChangeType](#type-inventorychangetype).
Default: [`PHYSICAL_COUNT`, `ADJUSTMENT`]. `TRANSFER` is not supported as
a filter.
See [InventoryChangeType](#type-inventorychangetype) for possible values | +| `states` | [`Array`](/doc/models/inventory-state.md) | Optional | Filters `ADJUSTMENT` query results by
[InventoryState](#type-inventorystate). Only applied when set.
Default: unset.
See [InventoryState](#type-inventorystate) for possible values | +| `updated_after` | `String` | Optional | Provided as an RFC 3339 timestamp. Returns results whose
`created_at` or `calculated_at` value is after the given time.
Default: UNIX epoch (`1970-01-01T00:00:00Z`). | +| `updated_before` | `String` | Optional | Provided as an RFC 3339 timestamp. Returns results whose
`created_at` or `calculated_at` value is strictly before the given time.
Default: UNIX epoch (`1970-01-01T00:00:00Z`). | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "catalog_object_ids": [ + "W62UWFY35CWMYGVWK6TWJDNI" + ], + "location_ids": [ + "C6W5YS5QM06F5" + ], + "types": [ + "PHYSICAL_COUNT" + ], + "states": [ + "IN_STOCK" + ], + "updated_after": "2016-11-01T00:00:00.000Z", + "updated_before": "2016-12-01T00:00:00.000Z" +} +``` + diff --git a/doc/models/batch-retrieve-inventory-changes-response.md b/doc/models/batch-retrieve-inventory-changes-response.md index 1d076f51..0c0b8ace 100644 --- a/doc/models/batch-retrieve-inventory-changes-response.md +++ b/doc/models/batch-retrieve-inventory-changes-response.md @@ -1,44 +1,44 @@ -## Batch Retrieve Inventory Changes Response - -### Structure - -`BatchRetrieveInventoryChangesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `changes` | [`Array`](/doc/models/inventory-change.md) | Optional | The current calculated inventory changes for the requested objects
and locations. | -| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "errors": [], - "changes": [ - { - "type": "PHYSICAL_COUNT", - "physical_count": { - "id": "46YDTW253DWGGK9HMAE6XCAO", - "reference_id": "22c07cf4-5626-4224-89f9-691112019399", - "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", - "catalog_object_type": "ITEM_VARIATION", - "state": "IN_STOCK", - "location_id": "C6W5YS5QM06F5", - "quantity": "86", - "source": { - "product": "SQUARE_POS", - "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0", - "name": "Square Point of Sale 4.37" - }, - "employee_id": "LRK57NSQ5X7PUD05", - "occurred_at": "2016-11-16T22:24:49.028Z", - "created_at": "2016-11-16T22:25:24.878Z" - } - } - ] -} -``` - +## Batch Retrieve Inventory Changes Response + +### Structure + +`BatchRetrieveInventoryChangesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `changes` | [`Array`](/doc/models/inventory-change.md) | Optional | The current calculated inventory changes for the requested objects
and locations. | +| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "errors": [], + "changes": [ + { + "type": "PHYSICAL_COUNT", + "physical_count": { + "id": "46YDTW253DWGGK9HMAE6XCAO", + "reference_id": "22c07cf4-5626-4224-89f9-691112019399", + "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", + "catalog_object_type": "ITEM_VARIATION", + "state": "IN_STOCK", + "location_id": "C6W5YS5QM06F5", + "quantity": "86", + "source": { + "product": "SQUARE_POS", + "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0", + "name": "Square Point of Sale 4.37" + }, + "employee_id": "LRK57NSQ5X7PUD05", + "occurred_at": "2016-11-16T22:24:49.028Z", + "created_at": "2016-11-16T22:25:24.878Z" + } + } + ] +} +``` + diff --git a/doc/models/batch-retrieve-inventory-counts-request.md b/doc/models/batch-retrieve-inventory-counts-request.md index ad737178..33ee3d61 100644 --- a/doc/models/batch-retrieve-inventory-counts-request.md +++ b/doc/models/batch-retrieve-inventory-counts-request.md @@ -1,29 +1,29 @@ -## Batch Retrieve Inventory Counts Request - -### Structure - -`BatchRetrieveInventoryCountsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `catalog_object_ids` | `Array` | Optional | Filters results by [CatalogObject](./models/catalog-object.md) ID.
Only applied when set. Default: unset. | -| `location_ids` | `Array` | Optional | Filters results by [Location](./models/location.md) ID. Only
applied when set. Default: unset. | -| `updated_after` | `String` | Optional | Provided as an RFC 3339 timestamp. Returns results whose
`calculated_at` value is after the given time. Default: UNIX epoch
(`1970-01-01T00:00:00Z`). | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "catalog_object_ids": [ - "W62UWFY35CWMYGVWK6TWJDNI" - ], - "location_ids": [ - "59TNP9SA8VGDA" - ], - "updated_after": "2016-11-16T00:00:00.000Z" -} -``` - +## Batch Retrieve Inventory Counts Request + +### Structure + +`BatchRetrieveInventoryCountsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `catalog_object_ids` | `Array` | Optional | Filters results by [CatalogObject](#type-catalogobject) ID.
Only applied when set. Default: unset. | +| `location_ids` | `Array` | Optional | Filters results by [Location](#type-location) ID. Only
applied when set. Default: unset. | +| `updated_after` | `String` | Optional | Provided as an RFC 3339 timestamp. Returns results whose
`calculated_at` value is after the given time. Default: UNIX epoch
(`1970-01-01T00:00:00Z`). | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "catalog_object_ids": [ + "W62UWFY35CWMYGVWK6TWJDNI" + ], + "location_ids": [ + "59TNP9SA8VGDA" + ], + "updated_after": "2016-11-16T00:00:00.000Z" +} +``` + diff --git a/doc/models/batch-retrieve-inventory-counts-response.md b/doc/models/batch-retrieve-inventory-counts-response.md index 47bc914a..4ac998a1 100644 --- a/doc/models/batch-retrieve-inventory-counts-response.md +++ b/doc/models/batch-retrieve-inventory-counts-response.md @@ -1,32 +1,32 @@ -## Batch Retrieve Inventory Counts Response - -### Structure - -`BatchRetrieveInventoryCountsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `counts` | [`Array`](/doc/models/inventory-count.md) | Optional | The current calculated inventory counts for the requested objects
and locations. | -| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "errors": [], - "counts": [ - { - "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", - "catalog_object_type": "ITEM_VARIATION", - "state": "IN_STOCK", - "location_id": "59TNP9SA8VGDA", - "quantity": "79", - "calculated_at": "2016-11-16T22:28:01.223Z" - } - ] -} -``` - +## Batch Retrieve Inventory Counts Response + +### Structure + +`BatchRetrieveInventoryCountsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `counts` | [`Array`](/doc/models/inventory-count.md) | Optional | The current calculated inventory counts for the requested objects
and locations. | +| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "errors": [], + "counts": [ + { + "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", + "catalog_object_type": "ITEM_VARIATION", + "state": "IN_STOCK", + "location_id": "59TNP9SA8VGDA", + "quantity": "79", + "calculated_at": "2016-11-16T22:28:01.223Z" + } + ] +} +``` + diff --git a/doc/models/batch-retrieve-orders-request.md b/doc/models/batch-retrieve-orders-request.md index a3759416..56b84923 100644 --- a/doc/models/batch-retrieve-orders-request.md +++ b/doc/models/batch-retrieve-orders-request.md @@ -1,26 +1,26 @@ -## Batch Retrieve Orders Request - +## Batch Retrieve Orders Request + Defines the fields that are included in requests to the -BatchRetrieveOrders endpoint. - -### Structure - -`BatchRetrieveOrdersRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `order_ids` | `Array` | The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request. | - -### Example (as JSON) - -```json -{ - "order_ids": [ - "CAISEM82RcpmcFBM0TfOyiHV3es", - "CAISENgvlJ6jLWAzERDzjyHVybY" - ] -} -``` - +BatchRetrieveOrders endpoint. + +### Structure + +`BatchRetrieveOrdersRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `order_ids` | `Array` | The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request. | + +### Example (as JSON) + +```json +{ + "order_ids": [ + "CAISEM82RcpmcFBM0TfOyiHV3es", + "CAISENgvlJ6jLWAzERDzjyHVybY" + ] +} +``` + diff --git a/doc/models/batch-retrieve-orders-response.md b/doc/models/batch-retrieve-orders-response.md index cfa15ca9..2991e0ed 100644 --- a/doc/models/batch-retrieve-orders-response.md +++ b/doc/models/batch-retrieve-orders-response.md @@ -1,62 +1,62 @@ -## Batch Retrieve Orders Response - -Defines the fields that are included in the response body of -a request to the BatchRetrieveOrders endpoint. - -### Structure - -`BatchRetrieveOrdersResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `orders` | [`Array`](/doc/models/order.md) | Optional | The requested orders. This will omit any requested orders that do not exist or are not charged. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "orders": [ - { - "id": "CAISEM82RcpmcFBM0TfOyiHV3es", - "location_id": "LOCATION_ID", - "reference_id": "my-order-001", - "line_items": [ - { - "id": "945986d1-9586-11e6-ad5a-28cfe92138cf", - "name": "Awesome product", - "quantity": "1", - "base_price_money": { - "amount": 1599, - "currency": "USD" - }, - "total_money": { - "amount": 1599, - "currency": "USD" - } - }, - { - "id": "a8f4168c-9586-11e6-bdf0-28cfe92138cf", - "name": "Another awesome product", - "quantity": "3", - "base_price_money": { - "amount": 2000, - "currency": "USD" - }, - "total_money": { - "amount": 6000, - "currency": "USD" - } - } - ], - "total_money": { - "amount": 7599, - "currency": "USD" - } - } - ] -} -``` - +## Batch Retrieve Orders Response + +Defines the fields that are included in the response body of +a request to the BatchRetrieveOrders endpoint. + +### Structure + +`BatchRetrieveOrdersResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `orders` | [`Array`](/doc/models/order.md) | Optional | The requested orders. This will omit any requested orders that do not exist. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "orders": [ + { + "id": "CAISEM82RcpmcFBM0TfOyiHV3es", + "location_id": "057P5VYJ4A5X1", + "reference_id": "my-order-001", + "line_items": [ + { + "uid": "945986d1-9586-11e6-ad5a-28cfe92138cf", + "name": "Awesome product", + "quantity": "1", + "base_price_money": { + "amount": 1599, + "currency": "USD" + }, + "total_money": { + "amount": 1599, + "currency": "USD" + } + }, + { + "uid": "a8f4168c-9586-11e6-bdf0-28cfe92138cf", + "name": "Another awesome product", + "quantity": "3", + "base_price_money": { + "amount": 2000, + "currency": "USD" + }, + "total_money": { + "amount": 6000, + "currency": "USD" + } + } + ], + "total_money": { + "amount": 7599, + "currency": "USD" + } + } + ] +} +``` + diff --git a/doc/models/batch-upsert-catalog-objects-request.md b/doc/models/batch-upsert-catalog-objects-request.md index 713b9720..6630004a 100644 --- a/doc/models/batch-upsert-catalog-objects-request.md +++ b/doc/models/batch-upsert-catalog-objects-request.md @@ -1,120 +1,120 @@ -## Batch Upsert Catalog Objects Request - -### Structure - -`BatchUpsertCatalogObjectsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `idempotency_key` | `String` | | A value you specify that uniquely identifies this
request among all your requests. A common way to create
a valid idempotency key is to use a Universally unique
identifier (UUID).

If you're unsure whether a particular request was successful,
you can reattempt it with the same idempotency key without
worrying about creating duplicate objects.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | -| `batches` | [`Array`](/doc/models/catalog-object-batch.md) | Optional | A batch of [CatalogObject](./models/catalog-object.md)s to be inserted/updated atomically.
The objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs
attempting to insert or update an object within a batch, the entire batch will be rejected. However, an error
in one batch will not affect other batches within the same request.

For each object, its `updated_at` field is ignored and replaced with a current [timestamp](#workingwithdates), and its
`is_deleted` field must not be set to `true`.

To modify an existing object, supply its ID. To create a new object, use an ID starting
with `#`. These IDs may be used to create relationships between an object and attributes of
other objects that reference it. For example, you can create a [CatalogItem](./models/catalog-item.md) with
ID `#ABC` and a [CatalogItemVariation](./models/catalog-item-variation.md) with its `item_id` attribute set to
`#ABC` in order to associate the [CatalogItemVariation](./models/catalog-item-variation.md) with its parent
[CatalogItem](./models/catalog-item.md).

Any `#`-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs.

Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request
may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will
be inserted or updated. | - -### Example (as JSON) - -```json -{ - "idempotency_key": "789ff020-f723-43a9-b4b5-43b5dc1fa3dc", - "batches": [ - { - "objects": [ - { - "type": "ITEM", - "id": "#Tea", - "present_at_all_locations": true, - "item_data": { - "name": "Tea", - "description": "Hot Leaf Juice", - "category_id": "#Beverages", - "tax_ids": [ - "#SalesTax" - ], - "variations": [ - { - "type": "ITEM_VARIATION", - "id": "#Tea_Mug", - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "#Tea", - "name": "Mug", - "pricing_type": "FIXED_PRICING", - "price_money": { - "amount": 150, - "currency": "USD" - } - } - } - ] - } - }, - { - "type": "ITEM", - "id": "#Coffee", - "present_at_all_locations": true, - "item_data": { - "name": "Coffee", - "description": "Hot Bean Juice", - "category_id": "#Beverages", - "tax_ids": [ - "#SalesTax" - ], - "variations": [ - { - "type": "ITEM_VARIATION", - "id": "#Coffee_Regular", - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "#Coffee", - "name": "Regular", - "pricing_type": "FIXED_PRICING", - "price_money": { - "amount": 250, - "currency": "USD" - } - } - }, - { - "type": "ITEM_VARIATION", - "id": "#Coffee_Large", - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "#Coffee", - "name": "Large", - "pricing_type": "FIXED_PRICING", - "price_money": { - "amount": 350, - "currency": "USD" - } - } - } - ] - } - }, - { - "type": "CATEGORY", - "id": "#Beverages", - "present_at_all_locations": true, - "category_data": { - "name": "Beverages" - } - }, - { - "type": "TAX", - "id": "#SalesTax", - "present_at_all_locations": true, - "tax_data": { - "name": "Sales Tax", - "calculation_phase": "TAX_SUBTOTAL_PHASE", - "inclusion_type": "ADDITIVE", - "percentage": "5.0", - "applies_to_custom_amounts": true, - "enabled": true - } - } - ] - } - ] -} -``` - +## Batch Upsert Catalog Objects Request + +### Structure + +`BatchUpsertCatalogObjectsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `String` | | A value you specify that uniquely identifies this
request among all your requests. A common way to create
a valid idempotency key is to use a Universally unique
identifier (UUID).

If you're unsure whether a particular request was successful,
you can reattempt it with the same idempotency key without
worrying about creating duplicate objects.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | +| `batches` | [`Array`](/doc/models/catalog-object-batch.md) | Optional | A batch of [CatalogObject](#type-catalogobject)s to be inserted/updated atomically.
The objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs
attempting to insert or update an object within a batch, the entire batch will be rejected. However, an error
in one batch will not affect other batches within the same request.

For each object, its `updated_at` field is ignored and replaced with a current [timestamp](#workingwithdates), and its
`is_deleted` field must not be set to `true`.

To modify an existing object, supply its ID. To create a new object, use an ID starting
with `#`. These IDs may be used to create relationships between an object and attributes of
other objects that reference it. For example, you can create a [CatalogItem](#type-catalogitem) with
ID `#ABC` and a [CatalogItemVariation](#type-catalogitemvariation) with its `item_id` attribute set to
`#ABC` in order to associate the [CatalogItemVariation](#type-catalogitemvariation) with its parent
[CatalogItem](#type-catalogitem).

Any `#`-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs.

Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request
may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will
be inserted or updated. | + +### Example (as JSON) + +```json +{ + "idempotency_key": "789ff020-f723-43a9-b4b5-43b5dc1fa3dc", + "batches": [ + { + "objects": [ + { + "type": "ITEM", + "id": "#Tea", + "present_at_all_locations": true, + "item_data": { + "name": "Tea", + "description": "Hot Leaf Juice", + "category_id": "#Beverages", + "tax_ids": [ + "#SalesTax" + ], + "variations": [ + { + "type": "ITEM_VARIATION", + "id": "#Tea_Mug", + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "#Tea", + "name": "Mug", + "pricing_type": "FIXED_PRICING", + "price_money": { + "amount": 150, + "currency": "USD" + } + } + } + ] + } + }, + { + "type": "ITEM", + "id": "#Coffee", + "present_at_all_locations": true, + "item_data": { + "name": "Coffee", + "description": "Hot Bean Juice", + "category_id": "#Beverages", + "tax_ids": [ + "#SalesTax" + ], + "variations": [ + { + "type": "ITEM_VARIATION", + "id": "#Coffee_Regular", + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "#Coffee", + "name": "Regular", + "pricing_type": "FIXED_PRICING", + "price_money": { + "amount": 250, + "currency": "USD" + } + } + }, + { + "type": "ITEM_VARIATION", + "id": "#Coffee_Large", + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "#Coffee", + "name": "Large", + "pricing_type": "FIXED_PRICING", + "price_money": { + "amount": 350, + "currency": "USD" + } + } + } + ] + } + }, + { + "type": "CATEGORY", + "id": "#Beverages", + "present_at_all_locations": true, + "category_data": { + "name": "Beverages" + } + }, + { + "type": "TAX", + "id": "#SalesTax", + "present_at_all_locations": true, + "tax_data": { + "name": "Sales Tax", + "calculation_phase": "TAX_SUBTOTAL_PHASE", + "inclusion_type": "ADDITIVE", + "percentage": "5.0", + "applies_to_custom_amounts": true, + "enabled": true + } + } + ] + } + ] +} +``` + diff --git a/doc/models/batch-upsert-catalog-objects-response.md b/doc/models/batch-upsert-catalog-objects-response.md index bc319441..5e273649 100644 --- a/doc/models/batch-upsert-catalog-objects-response.md +++ b/doc/models/batch-upsert-catalog-objects-response.md @@ -1,171 +1,171 @@ -## Batch Upsert Catalog Objects Response - -### Structure - -`BatchUpsertCatalogObjectsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `objects` | [`Array`](/doc/models/catalog-object.md) | Optional | The created [CatalogObject](./models/catalog-object.md)s | -| `updated_at` | `String` | Optional | The database [timestamp](#workingwithdates) of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | -| `id_mappings` | [`Array`](/doc/models/catalog-id-mapping.md) | Optional | The mapping between client and server IDs for this Upsert. | - -### Example (as JSON) - -```json -{ - "objects": [ - { - "type": "ITEM", - "id": "ZSDZN34NAXDLC6D5ZQMNSOUM", - "updated_at": "2017-05-10T18:48:39.798Z", - "version": 1494442119798, - "is_deleted": false, - "present_at_all_locations": true, - "item_data": { - "name": "Tea", - "description": "Hot Leaf Juice", - "category_id": "LYT72K3WGJFFCIMB63XARP3I", - "tax_ids": [ - "XHSHLHNWSI3HVI4BW5ZUZXI3" - ], - "variations": [ - { - "type": "ITEM_VARIATION", - "id": "NAYHET5R52MIYCEF34ZMAHFM", - "updated_at": "2017-05-10T18:48:39.798Z", - "version": 1494442119798, - "is_deleted": false, - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "ZSDZN34NAXDLC6D5ZQMNSOUM", - "name": "Mug", - "ordinal": 0, - "pricing_type": "FIXED_PRICING", - "price_money": { - "amount": 150, - "currency": "USD" - } - } - } - ] - } - }, - { - "type": "ITEM", - "id": "PJMCEBHHUS3OKDB6PYUHLCPP", - "updated_at": "2017-05-10T18:48:39.798Z", - "version": 1494442119798, - "is_deleted": false, - "present_at_all_locations": true, - "item_data": { - "name": "Coffee", - "description": "Hot Bean Juice", - "category_id": "LYT72K3WGJFFCIMB63XARP3I", - "tax_ids": [ - "XHSHLHNWSI3HVI4BW5ZUZXI3" - ], - "variations": [ - { - "type": "ITEM_VARIATION", - "id": "OTYDX45SPG7LJQUVCBZI4INH", - "updated_at": "2017-05-10T18:48:39.798Z", - "version": 1494442119798, - "is_deleted": false, - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "PJMCEBHHUS3OKDB6PYUHLCPP", - "name": "Regular", - "ordinal": 0, - "pricing_type": "FIXED_PRICING", - "price_money": { - "amount": 250, - "currency": "USD" - } - } - }, - { - "type": "ITEM_VARIATION", - "id": "GZDA3JB37FYVOPI4AOEBOITI", - "updated_at": "2017-05-10T18:48:39.798Z", - "version": 1494442119798, - "is_deleted": false, - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "PJMCEBHHUS3OKDB6PYUHLCPP", - "name": "Large", - "ordinal": 1, - "pricing_type": "FIXED_PRICING", - "price_money": { - "amount": 350, - "currency": "USD" - } - } - } - ] - } - }, - { - "type": "CATEGORY", - "id": "LYT72K3WGJFFCIMB63XARP3I", - "updated_at": "2017-05-10T18:48:39.798Z", - "version": 1494442119798, - "is_deleted": false, - "present_at_all_locations": true, - "category_data": { - "name": "Beverages" - } - }, - { - "type": "TAX", - "id": "XHSHLHNWSI3HVI4BW5ZUZXI3", - "updated_at": "2017-05-10T18:48:39.798Z", - "version": 1494442119798, - "is_deleted": false, - "present_at_all_locations": true, - "tax_data": { - "name": "Sales Tax", - "calculation_phase": "TAX_SUBTOTAL_PHASE", - "inclusion_type": "ADDITIVE", - "percentage": "5.0", - "applies_to_custom_amounts": true, - "enabled": true - } - } - ], - "id_mappings": [ - { - "client_object_id": "#Tea", - "object_id": "ZSDZN34NAXDLC6D5ZQMNSOUM" - }, - { - "client_object_id": "#Coffee", - "object_id": "PJMCEBHHUS3OKDB6PYUHLCPP" - }, - { - "client_object_id": "#Beverages", - "object_id": "LYT72K3WGJFFCIMB63XARP3I" - }, - { - "client_object_id": "#SalesTax", - "object_id": "XHSHLHNWSI3HVI4BW5ZUZXI3" - }, - { - "client_object_id": "#Tea_Mug", - "object_id": "NAYHET5R52MIYCEF34ZMAHFM" - }, - { - "client_object_id": "#Coffee_Regular", - "object_id": "OTYDX45SPG7LJQUVCBZI4INH" - }, - { - "client_object_id": "#Coffee_Large", - "object_id": "GZDA3JB37FYVOPI4AOEBOITI" - } - ] -} -``` - +## Batch Upsert Catalog Objects Response + +### Structure + +`BatchUpsertCatalogObjectsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `objects` | [`Array`](/doc/models/catalog-object.md) | Optional | The created [CatalogObject](#type-catalogobject)s | +| `updated_at` | `String` | Optional | The database [timestamp](#workingwithdates) of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | +| `id_mappings` | [`Array`](/doc/models/catalog-id-mapping.md) | Optional | The mapping between client and server IDs for this Upsert. | + +### Example (as JSON) + +```json +{ + "objects": [ + { + "type": "ITEM", + "id": "ZSDZN34NAXDLC6D5ZQMNSOUM", + "updated_at": "2017-05-10T18:48:39.798Z", + "version": 1494442119798, + "is_deleted": false, + "present_at_all_locations": true, + "item_data": { + "name": "Tea", + "description": "Hot Leaf Juice", + "category_id": "LYT72K3WGJFFCIMB63XARP3I", + "tax_ids": [ + "XHSHLHNWSI3HVI4BW5ZUZXI3" + ], + "variations": [ + { + "type": "ITEM_VARIATION", + "id": "NAYHET5R52MIYCEF34ZMAHFM", + "updated_at": "2017-05-10T18:48:39.798Z", + "version": 1494442119798, + "is_deleted": false, + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "ZSDZN34NAXDLC6D5ZQMNSOUM", + "name": "Mug", + "ordinal": 0, + "pricing_type": "FIXED_PRICING", + "price_money": { + "amount": 150, + "currency": "USD" + } + } + } + ] + } + }, + { + "type": "ITEM", + "id": "PJMCEBHHUS3OKDB6PYUHLCPP", + "updated_at": "2017-05-10T18:48:39.798Z", + "version": 1494442119798, + "is_deleted": false, + "present_at_all_locations": true, + "item_data": { + "name": "Coffee", + "description": "Hot Bean Juice", + "category_id": "LYT72K3WGJFFCIMB63XARP3I", + "tax_ids": [ + "XHSHLHNWSI3HVI4BW5ZUZXI3" + ], + "variations": [ + { + "type": "ITEM_VARIATION", + "id": "OTYDX45SPG7LJQUVCBZI4INH", + "updated_at": "2017-05-10T18:48:39.798Z", + "version": 1494442119798, + "is_deleted": false, + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "PJMCEBHHUS3OKDB6PYUHLCPP", + "name": "Regular", + "ordinal": 0, + "pricing_type": "FIXED_PRICING", + "price_money": { + "amount": 250, + "currency": "USD" + } + } + }, + { + "type": "ITEM_VARIATION", + "id": "GZDA3JB37FYVOPI4AOEBOITI", + "updated_at": "2017-05-10T18:48:39.798Z", + "version": 1494442119798, + "is_deleted": false, + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "PJMCEBHHUS3OKDB6PYUHLCPP", + "name": "Large", + "ordinal": 1, + "pricing_type": "FIXED_PRICING", + "price_money": { + "amount": 350, + "currency": "USD" + } + } + } + ] + } + }, + { + "type": "CATEGORY", + "id": "LYT72K3WGJFFCIMB63XARP3I", + "updated_at": "2017-05-10T18:48:39.798Z", + "version": 1494442119798, + "is_deleted": false, + "present_at_all_locations": true, + "category_data": { + "name": "Beverages" + } + }, + { + "type": "TAX", + "id": "XHSHLHNWSI3HVI4BW5ZUZXI3", + "updated_at": "2017-05-10T18:48:39.798Z", + "version": 1494442119798, + "is_deleted": false, + "present_at_all_locations": true, + "tax_data": { + "name": "Sales Tax", + "calculation_phase": "TAX_SUBTOTAL_PHASE", + "inclusion_type": "ADDITIVE", + "percentage": "5.0", + "applies_to_custom_amounts": true, + "enabled": true + } + } + ], + "id_mappings": [ + { + "client_object_id": "#Tea", + "object_id": "ZSDZN34NAXDLC6D5ZQMNSOUM" + }, + { + "client_object_id": "#Coffee", + "object_id": "PJMCEBHHUS3OKDB6PYUHLCPP" + }, + { + "client_object_id": "#Beverages", + "object_id": "LYT72K3WGJFFCIMB63XARP3I" + }, + { + "client_object_id": "#SalesTax", + "object_id": "XHSHLHNWSI3HVI4BW5ZUZXI3" + }, + { + "client_object_id": "#Tea_Mug", + "object_id": "NAYHET5R52MIYCEF34ZMAHFM" + }, + { + "client_object_id": "#Coffee_Regular", + "object_id": "OTYDX45SPG7LJQUVCBZI4INH" + }, + { + "client_object_id": "#Coffee_Large", + "object_id": "GZDA3JB37FYVOPI4AOEBOITI" + } + ] +} +``` + diff --git a/doc/models/break-type.md b/doc/models/break-type.md index 0f8e8c78..e7464934 100644 --- a/doc/models/break-type.md +++ b/doc/models/break-type.md @@ -1,37 +1,37 @@ -## Break Type - +## Break Type + A defined break template that sets an expectation for possible `Break` -instances on a `Shift`. - -### Structure - -`BreakType` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | UUID for this object. | -| `location_id` | `String` | | The ID of the business location this type of break applies to. | -| `break_name` | `String` | | A human-readable name for this type of break. Will be displayed to
employees in Square products. | -| `expected_duration` | `String` | | Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of
this break. Precision below minutes is truncated. | -| `is_paid` | `Boolean` | | Whether this break counts towards time worked for compensation
purposes. | -| `version` | `Integer` | Optional | Used for resolving concurrency issues; request will fail if version
provided does not match server version at time of request. If a value is not
provided, Square's servers execute a "blind" write; potentially
overwriting another writer's data. | -| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format. | -| `updated_at` | `String` | Optional | A read-only timestamp in RFC 3339 format. | - -### Example (as JSON) - -```json -{ - "id": null, - "location_id": "location_id4", - "break_name": "break_name8", - "expected_duration": "expected_duration4", - "is_paid": false, - "version": null, - "created_at": null, - "updated_at": null -} -``` - +instances on a `Shift`. + +### Structure + +`BreakType` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | UUID for this object. | +| `location_id` | `String` | | The ID of the business location this type of break applies to. | +| `break_name` | `String` | | A human-readable name for this type of break. Will be displayed to
employees in Square products. | +| `expected_duration` | `String` | | Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of
this break. Precision below minutes is truncated. | +| `is_paid` | `Boolean` | | Whether this break counts towards time worked for compensation
purposes. | +| `version` | `Integer` | Optional | Used for resolving concurrency issues; request will fail if version
provided does not match server version at time of request. If a value is not
provided, Square's servers execute a "blind" write; potentially
overwriting another writer's data. | +| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format. | +| `updated_at` | `String` | Optional | A read-only timestamp in RFC 3339 format. | + +### Example (as JSON) + +```json +{ + "id": null, + "location_id": "location_id4", + "break_name": "break_name8", + "expected_duration": "expected_duration4", + "is_paid": false, + "version": null, + "created_at": null, + "updated_at": null +} +``` + diff --git a/doc/models/break.md b/doc/models/break.md index 3bef0d3f..b7f35840 100644 --- a/doc/models/break.md +++ b/doc/models/break.md @@ -1,34 +1,34 @@ -## Break - -A record of an employee's break during a shift. - -### Structure - -`Break` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | UUID for this object | -| `start_at` | `String` | | RFC 3339; follows same timezone info as `Shift`. Precision up to
the minute is respected; seconds are truncated. | -| `end_at` | `String` | Optional | RFC 3339; follows same timezone info as `Shift`. Precision up to
the minute is respected; seconds are truncated. The `end_at` minute is not
counted when the break length is calculated. For example, a break from `00:00`
to `00:11` is considered a 10 minute break (midnight to 10 minutes after midnight). | -| `break_type_id` | `String` | | The `BreakType` this `Break` was templated on. | -| `name` | `String` | | A human-readable name. | -| `expected_duration` | `String` | | Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of
the break. | -| `is_paid` | `Boolean` | | Whether this break counts towards time worked for compensation
purposes. | - -### Example (as JSON) - -```json -{ - "id": null, - "start_at": "start_at2", - "end_at": null, - "break_type_id": "break_type_id6", - "name": "name0", - "expected_duration": "expected_duration4", - "is_paid": false -} -``` - +## Break + +A record of an employee's break during a shift. + +### Structure + +`Break` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | UUID for this object | +| `start_at` | `String` | | RFC 3339; follows same timezone info as `Shift`. Precision up to
the minute is respected; seconds are truncated. | +| `end_at` | `String` | Optional | RFC 3339; follows same timezone info as `Shift`. Precision up to
the minute is respected; seconds are truncated. The `end_at` minute is not
counted when the break length is calculated. For example, a break from `00:00`
to `00:11` is considered a 10 minute break (midnight to 10 minutes after midnight). | +| `break_type_id` | `String` | | The `BreakType` this `Break` was templated on. | +| `name` | `String` | | A human-readable name. | +| `expected_duration` | `String` | | Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of
the break. | +| `is_paid` | `Boolean` | | Whether this break counts towards time worked for compensation
purposes. | + +### Example (as JSON) + +```json +{ + "id": null, + "start_at": "start_at2", + "end_at": null, + "break_type_id": "break_type_id6", + "name": "name0", + "expected_duration": "expected_duration4", + "is_paid": false +} +``` + diff --git a/doc/models/business-hours-period.md b/doc/models/business-hours-period.md index 52f8a2b9..0fc11b8a 100644 --- a/doc/models/business-hours-period.md +++ b/doc/models/business-hours-period.md @@ -1,26 +1,26 @@ -## Business Hours Period - -Represents a period of time during which a business location is open. - -### Structure - -`BusinessHoursPeriod` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `day_of_week` | [`String (Day of Week)`](/doc/models/day-of-week.md) | Optional | Indicates the specific day of the week. | -| `start_local_time` | `String` | Optional | The start time of a business hours period, specified in local time using partial-time
RFC3339 format. | -| `end_local_time` | `String` | Optional | The end time of a business hours period, specified in local time using partial-time
RFC3339 format. | - -### Example (as JSON) - -```json -{ - "day_of_week": null, - "start_local_time": null, - "end_local_time": null -} -``` - +## Business Hours Period + +Represents a period of time during which a business location is open. + +### Structure + +`BusinessHoursPeriod` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `day_of_week` | [`String (Day of Week)`](/doc/models/day-of-week.md) | Optional | Indicates the specific day of the week. | +| `start_local_time` | `String` | Optional | The start time of a business hours period, specified in local time using partial-time
RFC3339 format. | +| `end_local_time` | `String` | Optional | The end time of a business hours period, specified in local time using partial-time
RFC3339 format. | + +### Example (as JSON) + +```json +{ + "day_of_week": null, + "start_local_time": null, + "end_local_time": null +} +``` + diff --git a/doc/models/business-hours.md b/doc/models/business-hours.md index b515c59c..5c9c0300 100644 --- a/doc/models/business-hours.md +++ b/doc/models/business-hours.md @@ -1,22 +1,22 @@ -## Business Hours - -Represents the hours of operation for a business location. - -### Structure - -`BusinessHours` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `periods` | [`Array`](/doc/models/business-hours-period.md) | Optional | The list of time periods during which the business is open. There may be at most 10
periods per day. | - -### Example (as JSON) - -```json -{ - "periods": null -} -``` - +## Business Hours + +Represents the hours of operation for a business location. + +### Structure + +`BusinessHours` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `periods` | [`Array`](/doc/models/business-hours-period.md) | Optional | The list of time periods during which the business is open. There may be at most 10
periods per day. | + +### Example (as JSON) + +```json +{ + "periods": null +} +``` + diff --git a/doc/models/cancel-payment-by-idempotency-key-request.md b/doc/models/cancel-payment-by-idempotency-key-request.md index 5ee8cbdb..a1e42b6c 100644 --- a/doc/models/cancel-payment-by-idempotency-key-request.md +++ b/doc/models/cancel-payment-by-idempotency-key-request.md @@ -1,22 +1,22 @@ -## Cancel Payment by Idempotency Key Request - -Specifies idempotency key of a payment to cancel. - -### Structure - -`CancelPaymentByIdempotencyKeyRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `idempotency_key` | `String` | `idempotency_key` identifying the payment to be canceled. | - -### Example (as JSON) - -```json -{ - "idempotency_key": "a7e36d40-d24b-11e8-b568-0800200c9a66" -} -``` - +## Cancel Payment by Idempotency Key Request + +Specifies idempotency key of a payment to cancel. + +### Structure + +`CancelPaymentByIdempotencyKeyRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `idempotency_key` | `String` | `idempotency_key` identifying the payment to be canceled. | + +### Example (as JSON) + +```json +{ + "idempotency_key": "a7e36d40-d24b-11e8-b568-0800200c9a66" +} +``` + diff --git a/doc/models/cancel-payment-by-idempotency-key-response.md b/doc/models/cancel-payment-by-idempotency-key-response.md index 98d74d63..f284d0dd 100644 --- a/doc/models/cancel-payment-by-idempotency-key-response.md +++ b/doc/models/cancel-payment-by-idempotency-key-response.md @@ -1,21 +1,21 @@ -## Cancel Payment by Idempotency Key Response - -Return value from the [CancelPaymentByIdempotencyKey](/doc/payments.md#cancelpaymentbyidempotencykey) endpoint. On success, -`errors` will be empty. - -### Structure - -`CancelPaymentByIdempotencyKeyResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{} -``` - +## Cancel Payment by Idempotency Key Response + +Return value from the [CancelPaymentByIdempotencyKey](#endpoint-payments-cancelpaymentbyidempotencykey) endpoint. On success, +`errors` will be empty. + +### Structure + +`CancelPaymentByIdempotencyKeyResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/cancel-payment-response.md b/doc/models/cancel-payment-response.md index 435f1753..a69654cb 100644 --- a/doc/models/cancel-payment-response.md +++ b/doc/models/cancel-payment-response.md @@ -1,56 +1,56 @@ -## Cancel Payment Response - -Return value from the [CancelPayment](/doc/payments.md#cancelpayment) endpoint. - -### Structure - -`CancelPaymentResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `payment` | [`Payment Hash`](/doc/models/payment.md) | Optional | Represents a payment processed by the Square API. | - -### Example (as JSON) - -```json -{ - "payment": { - "id": "YNR82sYrdgYlEEvJHnkJ7jrRuaB", - "created_at": "2018-10-17T20:38:46.743Z", - "updated_at": "2018-10-17T20:38:57.693Z", - "amount_money": { - "amount": 200, - "currency": "USD" - }, - "app_fee_money": { - "amount": 10, - "currency": "USD" - }, - "total_money": { - "amount": 200, - "currency": "USD" - }, - "status": "CANCELED", - "source_type": "CARD", - "card_details": { - "status": "VOIDED", - "card": { - "card_brand": "VISA", - "last_4": "1234", - "exp_month": 2, - "exp_year": 2024, - "fingerprint": "sq-1-9PP0tWfcM6vIsYmfsesdjfhduHSDFNdJFNDfDNFjdfjpseirDErsaP" - }, - "entry_method": "KEYED", - "cvv_status": "CVV_ACCEPTED", - "avs_status": "AVS_ACCEPTED", - "auth_result_code": "eWZBDh" - }, - "reference_id": "12323232323" - } -} -``` - +## Cancel Payment Response + +Return value from the [CancelPayment](#endpoint-payments-cancelpayment) endpoint. + +### Structure + +`CancelPaymentResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `payment` | [`Payment Hash`](/doc/models/payment.md) | Optional | Represents a payment processed by the Square API. | + +### Example (as JSON) + +```json +{ + "payment": { + "id": "YNR82sYrdgYlEEvJHnkJ7jrRuaB", + "created_at": "2018-10-17T20:38:46.743Z", + "updated_at": "2018-10-17T20:38:57.693Z", + "amount_money": { + "amount": 200, + "currency": "USD" + }, + "app_fee_money": { + "amount": 10, + "currency": "USD" + }, + "total_money": { + "amount": 200, + "currency": "USD" + }, + "status": "CANCELED", + "source_type": "CARD", + "card_details": { + "status": "VOIDED", + "card": { + "card_brand": "VISA", + "last_4": "1234", + "exp_month": 2, + "exp_year": 2024, + "fingerprint": "sq-1-9PP0tWfcM6vIsYmfsesdjfhduHSDFNdJFNDfDNFjdfjpseirDErsaP" + }, + "entry_method": "KEYED", + "cvv_status": "CVV_ACCEPTED", + "avs_status": "AVS_ACCEPTED", + "auth_result_code": "eWZBDh" + }, + "reference_id": "12323232323" + } +} +``` + diff --git a/doc/models/capture-transaction-response.md b/doc/models/capture-transaction-response.md index 28c210a2..10bea522 100644 --- a/doc/models/capture-transaction-response.md +++ b/doc/models/capture-transaction-response.md @@ -1,21 +1,21 @@ -## Capture Transaction Response - -Defines the fields that are included in the response body of -a request to the [CaptureTransaction](#endpoint-capturetransaction) endpoint. - -### Structure - -`CaptureTransactionResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{} -``` - +## Capture Transaction Response + +Defines the fields that are included in the response body of +a request to the [CaptureTransaction](#endpoint-capturetransaction) endpoint. + +### Structure + +`CaptureTransactionResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/card-brand.md b/doc/models/card-brand.md index 0f7bfbb3..d9b66f6e 100644 --- a/doc/models/card-brand.md +++ b/doc/models/card-brand.md @@ -1,22 +1,22 @@ -## Card Brand - -Indicates a card's brand, such as `VISA` or `MASTERCARD`. - -### Enumeration - -`CardBrand` - -### Fields - -| Name | Description | -| --- | --- | -| `OTHER_BRAND` | - | -| `VISA` | - | -| `MASTERCARD` | - | -| `AMERICAN_EXPRESS` | - | -| `DISCOVER` | - | -| `DISCOVER_DINERS` | - | -| `JCB` | - | -| `CHINA_UNIONPAY` | - | -| `SQUARE_GIFT_CARD` | - | - +## Card Brand + +Indicates a card's brand, such as `VISA` or `MASTERCARD`. + +### Enumeration + +`CardBrand` + +### Fields + +| Name | Description | +| --- | --- | +| `OTHER_BRAND` | - | +| `VISA` | - | +| `MASTERCARD` | - | +| `AMERICAN_EXPRESS` | - | +| `DISCOVER` | - | +| `DISCOVER_DINERS` | - | +| `JCB` | - | +| `CHINA_UNIONPAY` | - | +| `SQUARE_GIFT_CARD` | - | + diff --git a/doc/models/card-payment-details.md b/doc/models/card-payment-details.md index 616cbc0a..92e96b25 100644 --- a/doc/models/card-payment-details.md +++ b/doc/models/card-payment-details.md @@ -1,40 +1,46 @@ -## Card Payment Details - -Reflects the current status of a card payment. - -### Structure - -`CardPaymentDetails` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `status` | `String` | Optional | The card payment's current state. It can be one of: `AUTHORIZED`, `CAPTURED`, `VOIDED`,
`FAILED`. | -| `card` | [`Card Hash`](/doc/models/card.md) | Optional | Represents the payment details of a card to be used for payments. These
details are determined by the `card_nonce` generated by `SqPaymentForm`. | -| `entry_method` | `String` | Optional | The method used to enter the card's details for the payment. Can be
`KEYED`, `SWIPED`, `EMV`, `ON_FILE`, or `CONTACTLESS`. | -| `cvv_status` | `String` | Optional | Status code returned from the Card Verification Value (CVV) check. | -| `avs_status` | `String` | Optional | Status code returned from the Address Verification System (AVS) check. | -| `auth_result_code` | `String` | Optional | Status code returned by the card issuer that describes the payment's
authorization status. | -| `application_identifier` | `String` | Optional | For EMV payments, identifies the EMV application used for the payment | -| `application_name` | `String` | Optional | For EMV payments, the human-readable name of the EMV application used for the payment. | -| `application_cryptogram` | `String` | Optional | For EMV payments, the cryptogram generated for the payment. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | - -### Example (as JSON) - -```json -{ - "status": null, - "card": null, - "entry_method": null, - "cvv_status": null, - "avs_status": null, - "auth_result_code": null, - "application_identifier": null, - "application_name": null, - "application_cryptogram": null, - "errors": null -} -``` - +## Card Payment Details + +Reflects the current status of a card payment. + +### Structure + +`CardPaymentDetails` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `status` | `String` | Optional | The card payment's current state. It can be one of: `AUTHORIZED`, `CAPTURED`, `VOIDED`,
`FAILED`. | +| `card` | [`Card Hash`](/doc/models/card.md) | Optional | Represents the payment details of a card to be used for payments. These
details are determined by the `card_nonce` generated by `SqPaymentForm`. | +| `entry_method` | `String` | Optional | The method used to enter the card's details for the payment. Can be
`KEYED`, `SWIPED`, `EMV`, `ON_FILE`, or `CONTACTLESS`. | +| `cvv_status` | `String` | Optional | Status code returned from the Card Verification Value (CVV) check. Can be
`CVV_ACCEPTED`, `CVV_REJECTED`, `CVV_NOT_CHECKED`. | +| `avs_status` | `String` | Optional | Status code returned from the Address Verification System (AVS) check. Can be
`AVS_ACCEPTED`, `AVS_REJECTED`, `AVS_NOT_CHECKED`. | +| `auth_result_code` | `String` | Optional | Status code returned by the card issuer that describes the payment's
authorization status. | +| `application_identifier` | `String` | Optional | For EMV payments, identifies the EMV application used for the payment. | +| `application_name` | `String` | Optional | For EMV payments, the human-readable name of the EMV application used for the payment. | +| `application_cryptogram` | `String` | Optional | For EMV payments, the cryptogram generated for the payment. | +| `verification_method` | `String` | Optional | For EMV payments, method used to verify the cardholder's identity. Can be one of
`PIN`, `SIGNATURE`, `PIN_AND_SIGNATURE`, `ON_DEVICE`, or `NONE`. | +| `verification_results` | `String` | Optional | For EMV payments, the results of the cardholder verification. Can be one of
`SUCCESS`, `FAILURE`, or `UNKNOWN`. | +| `statement_description` | `String` | Optional | The statement description sent to the card networks.

Note: The actual statement description will vary and is likely to be truncated and appended with
additional information on a per issuer basis. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | + +### Example (as JSON) + +```json +{ + "status": null, + "card": null, + "entry_method": null, + "cvv_status": null, + "avs_status": null, + "auth_result_code": null, + "application_identifier": null, + "application_name": null, + "application_cryptogram": null, + "verification_method": null, + "verification_results": null, + "statement_description": null, + "errors": null +} +``` + diff --git a/doc/models/card.md b/doc/models/card.md index 3590e0d8..92c3d0eb 100644 --- a/doc/models/card.md +++ b/doc/models/card.md @@ -1,37 +1,39 @@ -## Card - -Represents the payment details of a card to be used for payments. These -details are determined by the `card_nonce` generated by `SqPaymentForm`. - -### Structure - -`Card` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | Unique ID for this card. Generated by Square. | -| `card_brand` | [`String (Card Brand)`](/doc/models/card-brand.md) | Optional | Indicates a card's brand, such as `VISA` or `MASTERCARD`. | -| `last_4` | `String` | Optional | The last 4 digits of the card number. | -| `exp_month` | `Long` | Optional | The expiration month of the associated card as an integer between 1 and 12. | -| `exp_year` | `Long` | Optional | The four-digit year of the card's expiration date. | -| `cardholder_name` | `String` | Optional | The name of the cardholder. | -| `billing_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `fingerprint` | `String` | Optional | A unique, Square-assigned ID that identifies the card across multiple
locations and applications for a single Square account. | - -### Example (as JSON) - -```json -{ - "id": null, - "card_brand": null, - "last_4": null, - "exp_month": null, - "exp_year": null, - "cardholder_name": null, - "billing_address": null, - "fingerprint": null -} -``` - +## Card + +Represents the payment details of a card to be used for payments. These +details are determined by the `card_nonce` generated by `SqPaymentForm`. + +### Structure + +`Card` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | Unique ID for this card. Generated by Square. | +| `card_brand` | [`String (Card Brand)`](/doc/models/card-brand.md) | Optional | Indicates a card's brand, such as `VISA` or `MASTERCARD`. | +| `last_4` | `String` | Optional | The last 4 digits of the card number. | +| `exp_month` | `Long` | Optional | The expiration month of the associated card as an integer between 1 and 12. | +| `exp_year` | `Long` | Optional | The four-digit year of the card's expiration date. | +| `cardholder_name` | `String` | Optional | The name of the cardholder. | +| `billing_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `fingerprint` | `String` | Optional | A unique, Square-assigned ID that identifies the card across multiple
locations and applications for a single Square account. | +| `bin` | `String` | Optional | The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API
returns this field. | + +### Example (as JSON) + +```json +{ + "id": null, + "card_brand": null, + "last_4": null, + "exp_month": null, + "exp_year": null, + "cardholder_name": null, + "billing_address": null, + "fingerprint": null, + "bin": null +} +``` + diff --git a/doc/models/catalog-category.md b/doc/models/catalog-category.md index f28f0e23..e78be578 100644 --- a/doc/models/catalog-category.md +++ b/doc/models/catalog-category.md @@ -1,29 +1,29 @@ -## Catalog Category - -A category to which an [CatalogItem](./models/catalog-item.md) belongs in the Catalog object model. - -### Structure - -`CatalogCategory` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The category's name. Searchable. This field has max length of 255 Unicode code points. | - -### Example (as JSON) - -```json -{ - "object": { - "type": "CATEGORY", - "id": "#Beverages", - "present_at_all_locations": true, - "category_data": { - "name": "Beverages" - } - } -} -``` - +## Catalog Category + +A category to which an [CatalogItem](#type-catalogitem) belongs in the Catalog object model. + +### Structure + +`CatalogCategory` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The category's name. Searchable. This field has max length of 255 Unicode code points. | + +### Example (as JSON) + +```json +{ + "object": { + "type": "CATEGORY", + "id": "#Beverages", + "present_at_all_locations": true, + "category_data": { + "name": "Beverages" + } + } +} +``` + diff --git a/doc/models/catalog-discount-type.md b/doc/models/catalog-discount-type.md index 767b71db..37c4f46c 100644 --- a/doc/models/catalog-discount-type.md +++ b/doc/models/catalog-discount-type.md @@ -1,17 +1,17 @@ -## Catalog Discount Type - -How to apply a [CatalogDiscount](./models/catalog-discount.md) to a [CatalogItem](./models/catalog-item.md). - -### Enumeration - -`CatalogDiscountType` - -### Fields - -| Name | Description | -| --- | --- | -| `FIXED_PERCENTAGE` | Apply the discount as a fixed percentage (e.g., 5%) off the item price. | -| `FIXED_AMOUNT` | Apply the discount as a fixed amount (e.g., $1.00) off the item price. | -| `VARIABLE_PERCENTAGE` | Apply the discount as a variable percentage off the item price. The percentage will be specified at the time of sale. | -| `VARIABLE_AMOUNT` | Apply the discount as a variable amount off the item price. The amount will be specified at the time of sale. | - +## Catalog Discount Type + +How to apply a [CatalogDiscount](#type-catalogdiscount) to a [CatalogItem](#type-catalogitem). + +### Enumeration + +`CatalogDiscountType` + +### Fields + +| Name | Description | +| --- | --- | +| `FIXED_PERCENTAGE` | Apply the discount as a fixed percentage (e.g., 5%) off the item price. | +| `FIXED_AMOUNT` | Apply the discount as a fixed amount (e.g., $1.00) off the item price. | +| `VARIABLE_PERCENTAGE` | Apply the discount as a variable percentage off the item price. The percentage will be specified at the time of sale. | +| `VARIABLE_AMOUNT` | Apply the discount as a variable amount off the item price. The amount will be specified at the time of sale. | + diff --git a/doc/models/catalog-discount.md b/doc/models/catalog-discount.md index aa251e92..08330a4c 100644 --- a/doc/models/catalog-discount.md +++ b/doc/models/catalog-discount.md @@ -1,38 +1,38 @@ -## Catalog Discount - -A discount in the Catalog object model. - -### Structure - -`CatalogDiscount` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The discount's name. Searchable. This field has max length of 255 Unicode code points. | -| `discount_type` | [`String (Catalog Discount Type)`](/doc/models/catalog-discount-type.md) | Optional | How to apply a [CatalogDiscount](./models/catalog-discount.md) to a [CatalogItem](./models/catalog-item.md). | -| `percentage` | `String` | Optional | The percentage of the discount as a string representation of a decimal number, using a `.` as the decimal
separator and without a `%` sign. A value of `7.5` corresponds to `7.5%`. Specify a percentage of `0` if `discount_type`
is `VARIABLE_PERCENTAGE`.

Do not include this field for amount-based or variable discounts. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `pin_required` | `Boolean` | Optional | Indicates whether a mobile staff member needs to enter their PIN to apply the
discount to a payment in the Square Point of Sale app. | -| `label_color` | `String` | Optional | The color of the discount's display label in the Square Point of Sale app. This must be a valid hex color code. | - -### Example (as JSON) - -```json -{ - "object": { - "type": "DISCOUNT", - "id": "#Maythe4th", - "present_at_all_locations": true, - "discount_data": { - "name": "Welcome to the Dark(Roast) Side!", - "discount_type": "FIXED_PERCENTAGE", - "percentage": "5.4", - "pin_required": false, - "label_color": "red" - } - } -} -``` - +## Catalog Discount + +A discount in the Catalog object model. + +### Structure + +`CatalogDiscount` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The discount's name. Searchable. This field has max length of 255 Unicode code points. | +| `discount_type` | [`String (Catalog Discount Type)`](/doc/models/catalog-discount-type.md) | Optional | How to apply a [CatalogDiscount](#type-catalogdiscount) to a [CatalogItem](#type-catalogitem). | +| `percentage` | `String` | Optional | The percentage of the discount as a string representation of a decimal number, using a `.` as the decimal
separator and without a `%` sign. A value of `7.5` corresponds to `7.5%`. Specify a percentage of `0` if `discount_type`
is `VARIABLE_PERCENTAGE`.

Do not include this field for amount-based or variable discounts. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `pin_required` | `Boolean` | Optional | Indicates whether a mobile staff member needs to enter their PIN to apply the
discount to a payment in the Square Point of Sale app. | +| `label_color` | `String` | Optional | The color of the discount's display label in the Square Point of Sale app. This must be a valid hex color code. | + +### Example (as JSON) + +```json +{ + "object": { + "type": "DISCOUNT", + "id": "#Maythe4th", + "present_at_all_locations": true, + "discount_data": { + "name": "Welcome to the Dark(Roast) Side!", + "discount_type": "FIXED_PERCENTAGE", + "percentage": "5.4", + "pin_required": false, + "label_color": "red" + } + } +} +``` + diff --git a/doc/models/catalog-id-mapping.md b/doc/models/catalog-id-mapping.md index a23634f8..1ce7b1a2 100644 --- a/doc/models/catalog-id-mapping.md +++ b/doc/models/catalog-id-mapping.md @@ -1,24 +1,24 @@ -## Catalog Id Mapping - -A mapping between a client-supplied temporary ID and a permanent server ID. - -### Structure - -`CatalogIdMapping` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `client_object_id` | `String` | Optional | The client-supplied, temporary `#`-prefixed ID for a new [CatalogObject](./models/catalog-object.md). | -| `object_id` | `String` | Optional | The permanent ID for the [CatalogObject](./models/catalog-object.md) created by the server. | - -### Example (as JSON) - -```json -{ - "client_object_id": null, - "object_id": null -} -``` - +## Catalog Id Mapping + +A mapping between a client-supplied temporary ID and a permanent server ID. + +### Structure + +`CatalogIdMapping` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `client_object_id` | `String` | Optional | The client-supplied, temporary `#`-prefixed ID for a new [CatalogObject](#type-catalogobject). | +| `object_id` | `String` | Optional | The permanent ID for the [CatalogObject](#type-catalogobject) created by the server. | + +### Example (as JSON) + +```json +{ + "client_object_id": null, + "object_id": null +} +``` + diff --git a/doc/models/catalog-image.md b/doc/models/catalog-image.md index fba25bde..93a50100 100644 --- a/doc/models/catalog-image.md +++ b/doc/models/catalog-image.md @@ -1,27 +1,27 @@ -## Catalog Image - +## Catalog Image + An image file to use in Square catalogs. Can be associated with catalog -items, item variations, and categories. - -### Structure - -`CatalogImage` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The internal name of this image. Identifies this image in calls to the
Connect APIs. | -| `url` | `String` | Optional | The URL of this image. Generated by Square after an image is uploaded
to the CreateCatalogImage endpoint. | -| `caption` | `String` | Optional | A caption that describes what is shown in the image. Displayed in the
Square Online Store. | - -### Example (as JSON) - -```json -{ - "name": null, - "url": null, - "caption": null -} -``` - +items, item variations, and categories. + +### Structure + +`CatalogImage` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The internal name of this image. Identifies this image in calls to the
Connect APIs. | +| `url` | `String` | Optional | The URL of this image. Generated by Square after an image is uploaded
to the CreateCatalogImage endpoint. | +| `caption` | `String` | Optional | A caption that describes what is shown in the image. Displayed in the
Square Online Store. | + +### Example (as JSON) + +```json +{ + "name": null, + "url": null, + "caption": null +} +``` + diff --git a/doc/models/catalog-info-response-limits.md b/doc/models/catalog-info-response-limits.md index 947a3dbb..1d995b00 100644 --- a/doc/models/catalog-info-response-limits.md +++ b/doc/models/catalog-info-response-limits.md @@ -1,40 +1,40 @@ -## Catalog Info Response Limits - -### Structure - -`CatalogInfoResponseLimits` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `batch_upsert_max_objects_per_batch` | `Integer` | Optional | The maximum number of objects that may appear within a single batch in a
`/v2/catalog/batch-upsert` request. | -| `batch_upsert_max_total_objects` | `Integer` | Optional | The maximum number of objects that may appear across all batches in a
`/v2/catalog/batch-upsert` request. | -| `batch_retrieve_max_object_ids` | `Integer` | Optional | The maximum number of object IDs that may appear in a `/v2/catalog/batch-retrieve`
request. | -| `search_max_page_limit` | `Integer` | Optional | The maximum number of results that may be returned in a page of a
`/v2/catalog/search` response. | -| `batch_delete_max_object_ids` | `Integer` | Optional | The maximum number of object IDs that may be included in a single
`/v2/catalog/batch-delete` request. | -| `update_item_taxes_max_item_ids` | `Integer` | Optional | The maximum number of item IDs that may be included in a single
`/v2/catalog/update-item-taxes` request. | -| `update_item_taxes_max_taxes_to_enable` | `Integer` | Optional | The maximum number of tax IDs to be enabled that may be included in a single
`/v2/catalog/update-item-taxes` request. | -| `update_item_taxes_max_taxes_to_disable` | `Integer` | Optional | The maximum number of tax IDs to be disabled that may be included in a single
`/v2/catalog/update-item-taxes` request. | -| `update_item_modifier_lists_max_item_ids` | `Integer` | Optional | The maximum number of item IDs that may be included in a single
`/v2/catalog/update-item-modifier-lists` request. | -| `update_item_modifier_lists_max_modifier_lists_to_enable` | `Integer` | Optional | The maximum number of modifier list IDs to be enabled that may be included in
a single `/v2/catalog/update-item-modifier-lists` request. | -| `update_item_modifier_lists_max_modifier_lists_to_disable` | `Integer` | Optional | The maximum number of modifier list IDs to be disabled that may be included in
a single `/v2/catalog/update-item-modifier-lists` request. | - -### Example (as JSON) - -```json -{ - "batch_upsert_max_objects_per_batch": null, - "batch_upsert_max_total_objects": null, - "batch_retrieve_max_object_ids": null, - "search_max_page_limit": null, - "batch_delete_max_object_ids": null, - "update_item_taxes_max_item_ids": null, - "update_item_taxes_max_taxes_to_enable": null, - "update_item_taxes_max_taxes_to_disable": null, - "update_item_modifier_lists_max_item_ids": null, - "update_item_modifier_lists_max_modifier_lists_to_enable": null, - "update_item_modifier_lists_max_modifier_lists_to_disable": null -} -``` - +## Catalog Info Response Limits + +### Structure + +`CatalogInfoResponseLimits` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `batch_upsert_max_objects_per_batch` | `Integer` | Optional | The maximum number of objects that may appear within a single batch in a
`/v2/catalog/batch-upsert` request. | +| `batch_upsert_max_total_objects` | `Integer` | Optional | The maximum number of objects that may appear across all batches in a
`/v2/catalog/batch-upsert` request. | +| `batch_retrieve_max_object_ids` | `Integer` | Optional | The maximum number of object IDs that may appear in a `/v2/catalog/batch-retrieve`
request. | +| `search_max_page_limit` | `Integer` | Optional | The maximum number of results that may be returned in a page of a
`/v2/catalog/search` response. | +| `batch_delete_max_object_ids` | `Integer` | Optional | The maximum number of object IDs that may be included in a single
`/v2/catalog/batch-delete` request. | +| `update_item_taxes_max_item_ids` | `Integer` | Optional | The maximum number of item IDs that may be included in a single
`/v2/catalog/update-item-taxes` request. | +| `update_item_taxes_max_taxes_to_enable` | `Integer` | Optional | The maximum number of tax IDs to be enabled that may be included in a single
`/v2/catalog/update-item-taxes` request. | +| `update_item_taxes_max_taxes_to_disable` | `Integer` | Optional | The maximum number of tax IDs to be disabled that may be included in a single
`/v2/catalog/update-item-taxes` request. | +| `update_item_modifier_lists_max_item_ids` | `Integer` | Optional | The maximum number of item IDs that may be included in a single
`/v2/catalog/update-item-modifier-lists` request. | +| `update_item_modifier_lists_max_modifier_lists_to_enable` | `Integer` | Optional | The maximum number of modifier list IDs to be enabled that may be included in
a single `/v2/catalog/update-item-modifier-lists` request. | +| `update_item_modifier_lists_max_modifier_lists_to_disable` | `Integer` | Optional | The maximum number of modifier list IDs to be disabled that may be included in
a single `/v2/catalog/update-item-modifier-lists` request. | + +### Example (as JSON) + +```json +{ + "batch_upsert_max_objects_per_batch": null, + "batch_upsert_max_total_objects": null, + "batch_retrieve_max_object_ids": null, + "search_max_page_limit": null, + "batch_delete_max_object_ids": null, + "update_item_taxes_max_item_ids": null, + "update_item_taxes_max_taxes_to_enable": null, + "update_item_taxes_max_taxes_to_disable": null, + "update_item_modifier_lists_max_item_ids": null, + "update_item_modifier_lists_max_modifier_lists_to_enable": null, + "update_item_modifier_lists_max_modifier_lists_to_disable": null +} +``` + diff --git a/doc/models/catalog-info-response.md b/doc/models/catalog-info-response.md index 571ed1db..61d7a82b 100644 --- a/doc/models/catalog-info-response.md +++ b/doc/models/catalog-info-response.md @@ -1,34 +1,34 @@ -## Catalog Info Response - -### Structure - -`CatalogInfoResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `limits` | [`Catalog Info Response Limits Hash`](/doc/models/catalog-info-response-limits.md) | Optional | - | -| `standard_unit_description_group` | [`Standard Unit Description Group Hash`](/doc/models/standard-unit-description-group.md) | Optional | Group of standard measurement units. | - -### Example (as JSON) - -```json -{ - "limits": { - "batch_upsert_max_objects_per_batch": 1000, - "batch_upsert_max_total_objects": 10000, - "batch_retrieve_max_object_ids": 1000, - "search_max_page_limit": 1000, - "batch_delete_max_object_ids": 200, - "update_item_taxes_max_item_ids": 1000, - "update_item_taxes_max_taxes_to_enable": 1000, - "update_item_taxes_max_taxes_to_disable": 1000, - "update_item_modifier_lists_max_item_ids": 1000, - "update_item_modifier_lists_max_modifier_lists_to_enable": 1000, - "update_item_modifier_lists_max_modifier_lists_to_disable": 1000 - } -} -``` - +## Catalog Info Response + +### Structure + +`CatalogInfoResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `limits` | [`Catalog Info Response Limits Hash`](/doc/models/catalog-info-response-limits.md) | Optional | - | +| `standard_unit_description_group` | [`Standard Unit Description Group Hash`](/doc/models/standard-unit-description-group.md) | Optional | Group of standard measurement units. | + +### Example (as JSON) + +```json +{ + "limits": { + "batch_upsert_max_objects_per_batch": 1000, + "batch_upsert_max_total_objects": 10000, + "batch_retrieve_max_object_ids": 1000, + "search_max_page_limit": 1000, + "batch_delete_max_object_ids": 200, + "update_item_taxes_max_item_ids": 1000, + "update_item_taxes_max_taxes_to_enable": 1000, + "update_item_taxes_max_taxes_to_disable": 1000, + "update_item_modifier_lists_max_item_ids": 1000, + "update_item_modifier_lists_max_modifier_lists_to_enable": 1000, + "update_item_modifier_lists_max_modifier_lists_to_disable": 1000 + } +} +``` + diff --git a/doc/models/catalog-item-modifier-list-info.md b/doc/models/catalog-item-modifier-list-info.md index f50b0a92..c67a8f1f 100644 --- a/doc/models/catalog-item-modifier-list-info.md +++ b/doc/models/catalog-item-modifier-list-info.md @@ -1,30 +1,30 @@ -## Catalog Item Modifier List Info - -Controls the properties of a [CatalogModifierList](./models/catalog-modifier-list.md) as it applies to this [CatalogItem](./models/catalog-item.md). - -### Structure - -`CatalogItemModifierListInfo` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `modifier_list_id` | `String` | | The ID of the [CatalogModifierList](./models/catalog-modifier.md) controlled by this [CatalogModifierListInfo](./models/catalog-modifier-list-info.md). | -| `modifier_overrides` | [`Array`](/doc/models/catalog-modifier-override.md) | Optional | A set of [CatalogModifierOverride](./models/catalog-modifier-override.md) objects that override whether a given [CatalogModifier](./models/catalog-modifier.md) is enabled by default. | -| `min_selected_modifiers` | `Integer` | Optional | If zero or larger, the smallest number of [CatalogModifier](./models/catalog-modifier.md)s that must be selected from this [CatalogModifierList](./models/catalog-modifier-list.md). | -| `max_selected_modifiers` | `Integer` | Optional | If zero or larger, the largest number of [CatalogModifier](./models/catalog-modifier.md)s that can be selected from this [CatalogModifierList](./models/catalog-modifier-list.md). | -| `enabled` | `Boolean` | Optional | If `true`, enable this [CatalogModifierList](./models/catalog-modifier-list.md). | - -### Example (as JSON) - -```json -{ - "modifier_list_id": "modifier_list_id6", - "modifier_overrides": null, - "min_selected_modifiers": null, - "max_selected_modifiers": null, - "enabled": null -} -``` - +## Catalog Item Modifier List Info + +Controls the properties of a [CatalogModifierList](#type-catalogmodifierlist) as it applies to this [CatalogItem](#type-catalogitem). + +### Structure + +`CatalogItemModifierListInfo` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `modifier_list_id` | `String` | | The ID of the [CatalogModifierList](#type-catalogmodifierlist) controlled by this [CatalogModifierListInfo](#type-catalogmodifierlistinfo). | +| `modifier_overrides` | [`Array`](/doc/models/catalog-modifier-override.md) | Optional | A set of [CatalogModifierOverride](#type-catalogmodifieroverride) objects that override whether a given [CatalogModifier](#type-catalogmodifier) is enabled by default. | +| `min_selected_modifiers` | `Integer` | Optional | If zero or larger, the smallest number of [CatalogModifier](#type-catalogmodifier)s that must be selected from this [CatalogModifierList](#type-catalogmodifierlist). | +| `max_selected_modifiers` | `Integer` | Optional | If zero or larger, the largest number of [CatalogModifier](#type-catalogmodifier)s that can be selected from this [CatalogModifierList](#type-catalogmodifierlist). | +| `enabled` | `Boolean` | Optional | If `true`, enable this [CatalogModifierList](#type-catalogmodifierlist). | + +### Example (as JSON) + +```json +{ + "modifier_list_id": "modifier_list_id6", + "modifier_overrides": null, + "min_selected_modifiers": null, + "max_selected_modifiers": null, + "enabled": null +} +``` + diff --git a/doc/models/catalog-item-option-for-item.md b/doc/models/catalog-item-option-for-item.md index 6391c7bd..1f30f916 100644 --- a/doc/models/catalog-item-option-for-item.md +++ b/doc/models/catalog-item-option-for-item.md @@ -1,23 +1,23 @@ -## Catalog Item Option for Item - +## Catalog Item Option for Item + A list of item option values that can be assigned to item variations. -For example, a t-shirt item may offer a color option or a size option. - -### Structure - -`CatalogItemOptionForItem` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `item_option_id` | `String` | Optional | The unique id of the item option, used to form the dimensions of the item option matrix in a specified order. | - -### Example (as JSON) - -```json -{ - "item_option_id": null -} -``` - +For example, a t-shirt item may offer a color option or a size option. + +### Structure + +`CatalogItemOptionForItem` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `item_option_id` | `String` | Optional | The unique id of the item option, used to form the dimensions of the item option matrix in a specified order. | + +### Example (as JSON) + +```json +{ + "item_option_id": null +} +``` + diff --git a/doc/models/catalog-item-option-value-for-item-variation.md b/doc/models/catalog-item-option-value-for-item-variation.md index 66e07ac5..39a937df 100644 --- a/doc/models/catalog-item-option-value-for-item-variation.md +++ b/doc/models/catalog-item-option-value-for-item-variation.md @@ -1,28 +1,28 @@ -## Catalog Item Option Value for Item Variation - -A [CatalogItemOptionValue](./models/catalog-item-option-value.md) links an item +## Catalog Item Option Value for Item Variation + +A [CatalogItemOptionValue](#type-catalogitemoptionvalue) links an item variation to an item option as an item option value. For example, a t-shirt item may offer a color option and a size option. An item option value would represent each variation of t-shirt: For example, “Color:Red, Size:Small” -or “Color:Blue, Size:Medium”. - -### Structure - -`CatalogItemOptionValueForItemVariation` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `item_option_id` | `String` | Optional | The unique id of an item option. | -| `item_option_value_id` | `String` | Optional | The unique id of the selected value for the item option. | - -### Example (as JSON) - -```json -{ - "item_option_id": null, - "item_option_value_id": null -} -``` - +or “Color:Blue, Size:Medium”. + +### Structure + +`CatalogItemOptionValueForItemVariation` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `item_option_id` | `String` | Optional | The unique id of an item option. | +| `item_option_value_id` | `String` | Optional | The unique id of the selected value for the item option. | + +### Example (as JSON) + +```json +{ + "item_option_id": null, + "item_option_value_id": null +} +``` + diff --git a/doc/models/catalog-item-option-value.md b/doc/models/catalog-item-option-value.md index 777567ab..2c2b2161 100644 --- a/doc/models/catalog-item-option-value.md +++ b/doc/models/catalog-item-option-value.md @@ -1,34 +1,34 @@ -## Catalog Item Option Value - +## Catalog Item Option Value + An enumerated value that can link a [CatalogItemVariation(#type-catalogitemvariation) to an item option as one of -its item option values. - -### Structure - -`CatalogItemOptionValue` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `item_option_id` | `String` | Optional | Unique ID of the associated item option. | -| `name` | `String` | Optional | Name of this item option value. Searchable. | -| `description` | `String` | Optional | The option value's human-readable description. | -| `color` | `String` | Optional | The HTML color for this value in the format #FFRRGGBB or #RRGGBB
(e.g., "#ff8d4e85"). Only displayed if parent Item Option's `show_colors`
flag is enabled.
value. | -| `ordinal` | `Integer` | Optional | Determines where this option value appears in a list of option values. | -| `item_variation_count` | `Long` | Optional | The number of [CatalogItemVariation(#type-catalogitemvariation)s that
currently make use of this Item Option value. Present only if `retrieve_counts`
was specified on the request used to retrieve the parent Item Option of this
value.

Maximum: 100 counts. | - -### Example (as JSON) - -```json -{ - "item_option_id": null, - "name": null, - "description": null, - "color": null, - "ordinal": null, - "item_variation_count": null -} -``` - +its item option values. + +### Structure + +`CatalogItemOptionValue` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `item_option_id` | `String` | Optional | Unique ID of the associated item option. | +| `name` | `String` | Optional | Name of this item option value. Searchable. | +| `description` | `String` | Optional | The option value's human-readable description. | +| `color` | `String` | Optional | The HTML color for this value in the format #FFRRGGBB or #RRGGBB
(e.g., "#ff8d4e85"). Only displayed if parent Item Option's `show_colors`
flag is enabled.
value. | +| `ordinal` | `Integer` | Optional | Determines where this option value appears in a list of option values. | +| `item_variation_count` | `Long` | Optional | The number of [CatalogItemVariation(#type-catalogitemvariation)s that
currently make use of this Item Option value. Present only if `retrieve_counts`
was specified on the request used to retrieve the parent Item Option of this
value.

Maximum: 100 counts. | + +### Example (as JSON) + +```json +{ + "item_option_id": null, + "name": null, + "description": null, + "color": null, + "ordinal": null, + "item_variation_count": null +} +``` + diff --git a/doc/models/catalog-item-option.md b/doc/models/catalog-item-option.md index d0aa2ec6..f05b5d92 100644 --- a/doc/models/catalog-item-option.md +++ b/doc/models/catalog-item-option.md @@ -1,32 +1,32 @@ -## Catalog Item Option - -A group of variations for a [CatalogItem](./models/catalog-item.md)'s. - -### Structure - -`CatalogItemOption` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The item option's display name for the seller. Must be unique across
all item options. Searchable. | -| `display_name` | `String` | Optional | The item option's display name for the customer. Searchable. | -| `description` | `String` | Optional | The item option's human-readable description. Displays for in the Square
Point of Sale app for the seller and in the Online Store or on receipts for the buyer. | -| `show_colors` | `Boolean` | Optional | If true, display colors for entries in `values` when present. | -| `values` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](./models/catalog-object.md)s containing the
[CatalogItemOptionValue](./models/catalog-item-option-value.md)s for this item. | -| `item_count` | `Long` | Optional | The number of [CatalogItem](./models/catalog-item.md)s currently associated
with this item option. Present only if the `include_counts` was specified
in the request. Any count over 100 will be returned as `100`. | - -### Example (as JSON) - -```json -{ - "name": null, - "display_name": null, - "description": null, - "show_colors": null, - "values": null, - "item_count": null -} -``` - +## Catalog Item Option + +A group of variations for a [CatalogItem](#type-catalogitem)'s. + +### Structure + +`CatalogItemOption` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The item option's display name for the seller. Must be unique across
all item options. Searchable. | +| `display_name` | `String` | Optional | The item option's display name for the customer. Searchable. | +| `description` | `String` | Optional | The item option's human-readable description. Displays for in the Square
Point of Sale app for the seller and in the Online Store or on receipts for the buyer. | +| `show_colors` | `Boolean` | Optional | If true, display colors for entries in `values` when present. | +| `values` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](#type-catalogobject)s containing the
[CatalogItemOptionValue](#type-catalogitemoptionvalue)s for this item. | +| `item_count` | `Long` | Optional | The number of [CatalogItem](#type-catalogitem)s currently associated
with this item option. Present only if the `include_counts` was specified
in the request. Any count over 100 will be returned as `100`. | + +### Example (as JSON) + +```json +{ + "name": null, + "display_name": null, + "description": null, + "show_colors": null, + "values": null, + "item_count": null +} +``` + diff --git a/doc/models/catalog-item-product-type.md b/doc/models/catalog-item-product-type.md index aad75f96..fbbd61e8 100644 --- a/doc/models/catalog-item-product-type.md +++ b/doc/models/catalog-item-product-type.md @@ -1,18 +1,18 @@ -## Catalog Item Product Type - -The type of a [CatalogItem](./models/catalog-item.md). Connect V2 only allows the creation of `REGULAR` or `APPOINTMENTS_SERVICE` items. - -### Enumeration - -`CatalogItemProductType` - -### Fields - -| Name | Description | -| --- | --- | -| `REGULAR` | An ordinary item. | -| `GIFT_CARD` | A Square gift card. | -| `APPOINTMENTS_SERVICE` | A service that can be booked using the Square Appointments app. | -| `RETAIL_ITEM` | An item associated with the Retail vertical. | -| `RESTAURANT_ITEM` | An item associated with the Restaurants vertical. | - +## Catalog Item Product Type + +The type of a [CatalogItem](#type-catalogitem). Connect V2 only allows the creation of `REGULAR` or `APPOINTMENTS_SERVICE` items. + +### Enumeration + +`CatalogItemProductType` + +### Fields + +| Name | Description | +| --- | --- | +| `REGULAR` | An ordinary item. | +| `GIFT_CARD` | A Square gift card. | +| `APPOINTMENTS_SERVICE` | A service that can be booked using the Square Appointments app. | +| `RETAIL_ITEM` | An item associated with the Retail vertical. | +| `RESTAURANT_ITEM` | An item associated with the Restaurants vertical. | + diff --git a/doc/models/catalog-item-variation.md b/doc/models/catalog-item-variation.md index 412d5830..5084e7b3 100644 --- a/doc/models/catalog-item-variation.md +++ b/doc/models/catalog-item-variation.md @@ -1,51 +1,51 @@ -## Catalog Item Variation - -An item variation (i.e., product) in the Catalog object model. Each item -may have a maximum of 250 item variations. - -### Structure - -`CatalogItemVariation` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `item_id` | `String` | Optional | The ID of the [CatalogItem](./models/catalog-item.md) associated with this item variation. Searchable. | -| `name` | `String` | Optional | The item variation's name. Searchable. This field has max length of 255 Unicode code points. | -| `sku` | `String` | Optional | The item variation's SKU, if any. Searchable. | -| `upc` | `String` | Optional | The item variation's UPC, if any. Searchable in the Connect API.
This field is only exposed in the Connect API. It is not exposed in Square's Dashboard,
Square Point of Sale app or Retail Point of Sale app. | -| `ordinal` | `Integer` | Optional | The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal
for each item variation within a parent [CatalogItem](./models/catalog-item.md) is set according to the item variations's
position. On reads, the value is not guaranteed to be sequential or unique. | -| `pricing_type` | [`String (Catalog Pricing Type)`](/doc/models/catalog-pricing-type.md) | Optional | Indicates whether the price of a [CatalogItemVariation](./models/catalog-item-variation.md) should be entered manually at the time of sale. | -| `price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `location_overrides` | [`Array`](/doc/models/item-variation-location-overrides.md) | Optional | Per-[location](./models/location.md) price and inventory overrides. | -| `track_inventory` | `Boolean` | Optional | If `true`, inventory tracking is active for the variation. | -| `inventory_alert_type` | [`String (Inventory Alert Type)`](/doc/models/inventory-alert-type.md) | Optional | Indicates whether Square should alert the merchant when the inventory quantity of a [CatalogItemVariation](./models/catalog-item-variation.md) is low. | -| `inventory_alert_threshold` | `Long` | Optional | If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`
is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.

This value is always an integer. | -| `user_data` | `String` | Optional | Arbitrary user metadata to associate with the item variation. Cannot exceed 255 characters. Searchable. | -| `service_duration` | `Long` | Optional | If the [CatalogItem](./models/catalog-item.md) that owns this item variation is of type
`APPOINTMENTS_SERVICE`, then this is the duration of the service in milliseconds. For
example, a 30 minute appointment would have the value `1800000`, which is equal to
30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second). | -| `item_option_values` | [`Array`](/doc/models/catalog-item-option-value-for-item-variation.md) | Optional | List of item option values associated with this item variation. Listed
in the same order as the item options of the parent item. | -| `measurement_unit_id` | `String` | Optional | ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity
sold of this item variation. If left unset, the item will be sold in
whole quantities. | - -### Example (as JSON) - -```json -{ - "item_id": null, - "name": null, - "sku": null, - "upc": null, - "ordinal": null, - "pricing_type": null, - "price_money": null, - "location_overrides": null, - "track_inventory": null, - "inventory_alert_type": null, - "inventory_alert_threshold": null, - "user_data": null, - "service_duration": null, - "item_option_values": null, - "measurement_unit_id": null -} -``` - +## Catalog Item Variation + +An item variation (i.e., product) in the Catalog object model. Each item +may have a maximum of 250 item variations. + +### Structure + +`CatalogItemVariation` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `item_id` | `String` | Optional | The ID of the [CatalogItem](#type-catalogitem) associated with this item variation. Searchable. | +| `name` | `String` | Optional | The item variation's name. Searchable. This field has max length of 255 Unicode code points. | +| `sku` | `String` | Optional | The item variation's SKU, if any. Searchable. | +| `upc` | `String` | Optional | The item variation's UPC, if any. Searchable in the Connect API.
This field is only exposed in the Connect API. It is not exposed in Square's Dashboard,
Square Point of Sale app or Retail Point of Sale app. | +| `ordinal` | `Integer` | Optional | The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal
for each item variation within a parent [CatalogItem](#type-catalogitem) is set according to the item variations's
position. On reads, the value is not guaranteed to be sequential or unique. | +| `pricing_type` | [`String (Catalog Pricing Type)`](/doc/models/catalog-pricing-type.md) | Optional | Indicates whether the price of a [CatalogItemVariation](#type-catalogitemvariation) should be entered manually at the time of sale. | +| `price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `location_overrides` | [`Array`](/doc/models/item-variation-location-overrides.md) | Optional | Per-[location](#type-location) price and inventory overrides. | +| `track_inventory` | `Boolean` | Optional | If `true`, inventory tracking is active for the variation. | +| `inventory_alert_type` | [`String (Inventory Alert Type)`](/doc/models/inventory-alert-type.md) | Optional | Indicates whether Square should alert the merchant when the inventory quantity of a [CatalogItemVariation](#type-catalogitemvariation) is low. | +| `inventory_alert_threshold` | `Long` | Optional | If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`
is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.

This value is always an integer. | +| `user_data` | `String` | Optional | Arbitrary user metadata to associate with the item variation. Cannot exceed 255 characters. Searchable. | +| `service_duration` | `Long` | Optional | If the [CatalogItem](#type-catalogitem) that owns this item variation is of type
`APPOINTMENTS_SERVICE`, then this is the duration of the service in milliseconds. For
example, a 30 minute appointment would have the value `1800000`, which is equal to
30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second). | +| `item_option_values` | [`Array`](/doc/models/catalog-item-option-value-for-item-variation.md) | Optional | List of item option values associated with this item variation. Listed
in the same order as the item options of the parent item. | +| `measurement_unit_id` | `String` | Optional | ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity
sold of this item variation. If left unset, the item will be sold in
whole quantities. | + +### Example (as JSON) + +```json +{ + "item_id": null, + "name": null, + "sku": null, + "upc": null, + "ordinal": null, + "pricing_type": null, + "price_money": null, + "location_overrides": null, + "track_inventory": null, + "inventory_alert_type": null, + "inventory_alert_threshold": null, + "user_data": null, + "service_duration": null, + "item_option_values": null, + "measurement_unit_id": null +} +``` + diff --git a/doc/models/catalog-item.md b/doc/models/catalog-item.md index e1f4142b..cf343090 100644 --- a/doc/models/catalog-item.md +++ b/doc/models/catalog-item.md @@ -1,45 +1,45 @@ -## Catalog Item - -An item (i.e., product family) in the Catalog object model. - -### Structure - -`CatalogItem` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The item's name. Searchable. This field must not be empty. This field has max length of 512 Unicode code points. | -| `description` | `String` | Optional | The item's description. Searchable. This field has max length of 4096 Unicode code points. | -| `abbreviation` | `String` | Optional | The text of the item's display label in the Square Point of Sale app. Only up to the first five characters of the string are used. Searchable.
This field has max length of 24 Unicode code points. | -| `label_color` | `String` | Optional | The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code. | -| `available_online` | `Boolean` | Optional | If `true`, the item can be added to shipping orders from the merchant's online store. | -| `available_for_pickup` | `Boolean` | Optional | If `true`, the item can be added to pickup orders from the merchant's online store. | -| `available_electronically` | `Boolean` | Optional | If `true`, the item can be added to electronically fulfilled orders from the merchant's online store. | -| `category_id` | `String` | Optional | The ID of the item's category, if any. | -| `tax_ids` | `Array` | Optional | A set of IDs indicating the [CatalogTax](./models/catalog-tax.md)es that are enabled for
this item. When updating an item, any taxes listed here will be added to the item.
[CatalogTax](./models/catalog-tax.md)es may also be added to or deleted from an item using `UpdateItemTaxes`. | -| `modifier_list_info` | [`Array`](/doc/models/catalog-item-modifier-list-info.md) | Optional | A set of [CatalogItemModifierListInfo](./models/catalog-item-modifier-list-info.md) objects
representing the modifier lists that apply to this item, along with the overrides and min
and max limits that are specific to this item. [CatalogModifierList](./models/catalog-modifier-list.md)s
may also be added to or deleted from an item using `UpdateItemModifierLists`. | -| `variations` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](./models/catalog-object.md)s containing the
[CatalogItemVariation](./models/catalog-item-variation.md)s for this item.

Maximum: 250 item variations | -| `product_type` | [`String (Catalog Item Product Type)`](/doc/models/catalog-item-product-type.md) | Optional | The type of a [CatalogItem](./models/catalog-item.md). Connect V2 only allows the creation of `REGULAR` or `APPOINTMENTS_SERVICE` items. | -| `skip_modifier_screen` | `Boolean` | Optional | If `false`, the Square Point of Sale app will present the [CatalogItem](./models/catalog-item.md)'s
details screen immediately, allowing the merchant to choose [CatalogModifier](./models/catalog-modifier.md)s
before adding the item to the cart. This is the default behavior.

If `true`, the Square Point of Sale app will immediately add the item to the cart with the pre-selected
modifiers, and merchants can edit modifiers by drilling down onto the item's details.

Third-party clients are encouraged to implement similar behaviors. | -| `item_options` | [`Array`](/doc/models/catalog-item-option-for-item.md) | Optional | List of item options IDs for this item. Used to manage and group item
variations in a specified order.

Maximum: 6 item options. | - -### Example (as JSON) - -```json -{ - "object": { - "type": "ITEM", - "id": "#Cocoa", - "present_at_all_locations": true, - "item_data": { - "name": "Cocoa", - "description": "Hot chocolate", - "abbreviation": "Ch", - "visibility": "PRIVATE" - } - } -} -``` - +## Catalog Item + +An item (i.e., product family) in the Catalog object model. + +### Structure + +`CatalogItem` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The item's name. Searchable. This field must not be empty. This field has max length of 512 Unicode code points. | +| `description` | `String` | Optional | The item's description. Searchable. This field has max length of 4096 Unicode code points. | +| `abbreviation` | `String` | Optional | The text of the item's display label in the Square Point of Sale app. Only up to the first five characters of the string are used. Searchable.
This field has max length of 24 Unicode code points. | +| `label_color` | `String` | Optional | The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code. | +| `available_online` | `Boolean` | Optional | If `true`, the item can be added to shipping orders from the merchant's online store. | +| `available_for_pickup` | `Boolean` | Optional | If `true`, the item can be added to pickup orders from the merchant's online store. | +| `available_electronically` | `Boolean` | Optional | If `true`, the item can be added to electronically fulfilled orders from the merchant's online store. | +| `category_id` | `String` | Optional | The ID of the item's category, if any. | +| `tax_ids` | `Array` | Optional | A set of IDs indicating the [CatalogTax](#type-catalogtax)es that are enabled for
this item. When updating an item, any taxes listed here will be added to the item.
[CatalogTax](#type-catalogtax)es may also be added to or deleted from an item using `UpdateItemTaxes`. | +| `modifier_list_info` | [`Array`](/doc/models/catalog-item-modifier-list-info.md) | Optional | A set of [CatalogItemModifierListInfo](#type-catalogitemmodifierlistinfo) objects
representing the modifier lists that apply to this item, along with the overrides and min
and max limits that are specific to this item. [CatalogModifierList](#type-catalogmodifierlist)s
may also be added to or deleted from an item using `UpdateItemModifierLists`. | +| `variations` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](#type-catalogobject)s containing the
[CatalogItemVariation](#type-catalogitemvariation)s for this item.

Maximum: 250 item variations | +| `product_type` | [`String (Catalog Item Product Type)`](/doc/models/catalog-item-product-type.md) | Optional | The type of a [CatalogItem](#type-catalogitem). Connect V2 only allows the creation of `REGULAR` or `APPOINTMENTS_SERVICE` items. | +| `skip_modifier_screen` | `Boolean` | Optional | If `false`, the Square Point of Sale app will present the [CatalogItem](#type-catalogitem)'s
details screen immediately, allowing the merchant to choose [CatalogModifier](#type-catalogmodifier)s
before adding the item to the cart. This is the default behavior.

If `true`, the Square Point of Sale app will immediately add the item to the cart with the pre-selected
modifiers, and merchants can edit modifiers by drilling down onto the item's details.

Third-party clients are encouraged to implement similar behaviors. | +| `item_options` | [`Array`](/doc/models/catalog-item-option-for-item.md) | Optional | List of item options IDs for this item. Used to manage and group item
variations in a specified order.

Maximum: 6 item options. | + +### Example (as JSON) + +```json +{ + "object": { + "type": "ITEM", + "id": "#Cocoa", + "present_at_all_locations": true, + "item_data": { + "name": "Cocoa", + "description": "Hot chocolate", + "abbreviation": "Ch", + "visibility": "PRIVATE" + } + } +} +``` + diff --git a/doc/models/catalog-measurement-unit.md b/doc/models/catalog-measurement-unit.md index efc021d3..13845754 100644 --- a/doc/models/catalog-measurement-unit.md +++ b/doc/models/catalog-measurement-unit.md @@ -1,26 +1,26 @@ -## Catalog Measurement Unit - -Represents the unit used to measure a -[CatalogItemVariation](./models/catalog-item-variation.md) and specifies the precision -for decimal quantities. - -### Structure - -`CatalogMeasurementUnit` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `measurement_unit` | [`Measurement Unit Hash`](/doc/models/measurement-unit.md) | Optional | Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required: `custom_unit`,
`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`.

The `family` field describes the type of measurement. For example,
ounces are in the weight family. | -| `precision` | `Integer` | Optional | Represents the maximum number of positions allowed after the decimal
in quantities measured with this unit. For example, if the precision is 2,
then an itemization’s quantity can be 0.01, 0.12, etc.

Min: 0

Max: 5

Default: 3 | - -### Example (as JSON) - -```json -{ - "measurement_unit": null, - "precision": null -} -``` - +## Catalog Measurement Unit + +Represents the unit used to measure a +[CatalogItemVariation](#type-catalogitemvariation) and specifies the precision +for decimal quantities. + +### Structure + +`CatalogMeasurementUnit` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `measurement_unit` | [`Measurement Unit Hash`](/doc/models/measurement-unit.md) | Optional | Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required: `custom_unit`,
`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`. | +| `precision` | `Integer` | Optional | Represents the maximum number of positions allowed after the decimal
in quantities measured with this unit. For example, if the precision is 2,
then an itemization’s quantity can be 0.01, 0.12, etc.

Min: 0

Max: 5

Default: 3 | + +### Example (as JSON) + +```json +{ + "measurement_unit": null, + "precision": null +} +``` + diff --git a/doc/models/catalog-modifier-list-selection-type.md b/doc/models/catalog-modifier-list-selection-type.md index 885eed69..62a0dccc 100644 --- a/doc/models/catalog-modifier-list-selection-type.md +++ b/doc/models/catalog-modifier-list-selection-type.md @@ -1,15 +1,15 @@ -## Catalog Modifier List Selection Type - -Indicates whether a [CatalogModifierList](./models/catalog-modifier-list.md) supports multiple selections. - -### Enumeration - -`CatalogModifierListSelectionType` - -### Fields - -| Name | Description | -| --- | --- | -| `SINGLE` | Indicates that a [CatalogModifierList](./models/catalog-modifier.md) allows only a
single [CatalogModifier](./models/catalog-modifier.md) to be selected. | -| `MULTIPLE` | Indicates that a [CatalogModifierList](./models/catalog-modifier-list.md) allows multiple
[CatalogModifier](./models/catalog-modifier.md) to be selected. | - +## Catalog Modifier List Selection Type + +Indicates whether a [CatalogModifierList](#type-catalogmodifierlist) supports multiple selections. + +### Enumeration + +`CatalogModifierListSelectionType` + +### Fields + +| Name | Description | +| --- | --- | +| `SINGLE` | Indicates that a [CatalogModifierList](#type-catalogmodifierlist) allows only a
single [CatalogModifier](#type-catalogmodifier) to be selected. | +| `MULTIPLE` | Indicates that a [CatalogModifierList](#type-catalogmodifierlist) allows multiple
[CatalogModifier](#type-catalogmodifier) to be selected. | + diff --git a/doc/models/catalog-modifier-list.md b/doc/models/catalog-modifier-list.md index bf215b53..9e6ca8db 100644 --- a/doc/models/catalog-modifier-list.md +++ b/doc/models/catalog-modifier-list.md @@ -1,71 +1,71 @@ -## Catalog Modifier List - -A modifier list in the Catalog object model. A [CatalogModifierList](./models/modifier.md) -contains [Modifier](./models/catalog-modifier.md)s that can be applied to a [CatalogItem](./models/catalog-item.md) -at the time of sale. - -For example, a modifier list "Condiments" that would apply to a "Hot Dog" [CatalogItem](./models/catalog-item.md) might -contain [CatalogModifier](./models/catalog-modifier.md)s "Ketchup", "Mustard", and "Relish". The -`selection_type` field specifies whether or not multiple selections from the modifier list are allowed. - -### Structure - -`CatalogModifierList` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The [CatalogModifierList](./models/catalog-modifier-list.md)'s name. Searchable. This field has max length of 255 Unicode code points. | -| `selection_type` | [`String (Catalog Modifier List Selection Type)`](/doc/models/catalog-modifier-list-selection-type.md) | Optional | Indicates whether a [CatalogModifierList](./models/catalog-modifier-list.md) supports multiple selections. | -| `modifiers` | [`Array`](/doc/models/catalog-object.md) | Optional | The options included in the [CatalogModifierList](./models/catalog-modifier-list.md).
You must include at least one [CatalogModifier](./models/catalog-modifier.md).
Each [CatalogObject](./models/catalog-object.md) must have type `MODIFIER` and contain
[CatalogModifier](./models/catalog-modifier.md) data. | - -### Example (as JSON) - -```json -{ - "type": "MODIFIER_LIST", - "id": "#MilkType", - "present_at_all_locations": true, - "modifier_list_data": { - "name": "Milk Type", - "selection_type": "SINGLE", - "modifiers": [ - { - "type": "MODIFIER", - "present_at_all_locations": true, - "modifier_data": { - "name": "Whole Milk", - "price_money": { - "amount": 0, - "currency": "USD" - } - } - }, - { - "type": "MODIFIER", - "present_at_all_locations": true, - "modifier_data": { - "name": "Almond Milk", - "price_money": { - "amount": 250, - "currency": "USD" - } - } - }, - { - "type": "MODIFIER", - "present_at_all_locations": true, - "modifier_data": { - "name": "Soy Milk", - "price_money": { - "amount": 250, - "currency": "USD" - } - } - } - ] - } -} -``` - +## Catalog Modifier List + +A modifier list in the Catalog object model. A [CatalogModifierList](#type-catalogmodifierlist) +contains [Modifier](#type-catalogmodifier)s that can be applied to a [CatalogItem](#type-catalogitem) +at the time of sale. + +For example, a modifier list "Condiments" that would apply to a "Hot Dog" [CatalogItem](#type-catalogitem) might +contain [CatalogModifier](#type-catalogmodifier)s "Ketchup", "Mustard", and "Relish". The +`selection_type` field specifies whether or not multiple selections from the modifier list are allowed. + +### Structure + +`CatalogModifierList` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The [CatalogModifierList](#type-catalogmodifierlist)'s name. Searchable. This field has max length of 255 Unicode code points. | +| `selection_type` | [`String (Catalog Modifier List Selection Type)`](/doc/models/catalog-modifier-list-selection-type.md) | Optional | Indicates whether a [CatalogModifierList](#type-catalogmodifierlist) supports multiple selections. | +| `modifiers` | [`Array`](/doc/models/catalog-object.md) | Optional | The options included in the [CatalogModifierList](#type-catalogmodifierlist).
You must include at least one [CatalogModifier](#type-catalogmodifier).
Each [CatalogObject](#type-catalogobject) must have type `MODIFIER` and contain
[CatalogModifier](#type-catalogmodifier) data. | + +### Example (as JSON) + +```json +{ + "type": "MODIFIER_LIST", + "id": "#MilkType", + "present_at_all_locations": true, + "modifier_list_data": { + "name": "Milk Type", + "selection_type": "SINGLE", + "modifiers": [ + { + "type": "MODIFIER", + "present_at_all_locations": true, + "modifier_data": { + "name": "Whole Milk", + "price_money": { + "amount": 0, + "currency": "USD" + } + } + }, + { + "type": "MODIFIER", + "present_at_all_locations": true, + "modifier_data": { + "name": "Almond Milk", + "price_money": { + "amount": 250, + "currency": "USD" + } + } + }, + { + "type": "MODIFIER", + "present_at_all_locations": true, + "modifier_data": { + "name": "Soy Milk", + "price_money": { + "amount": 250, + "currency": "USD" + } + } + } + ] + } +} +``` + diff --git a/doc/models/catalog-modifier-override.md b/doc/models/catalog-modifier-override.md index 1ef112aa..c3d260df 100644 --- a/doc/models/catalog-modifier-override.md +++ b/doc/models/catalog-modifier-override.md @@ -1,22 +1,22 @@ -## Catalog Modifier Override - -### Structure - -`CatalogModifierOverride` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `modifier_id` | `String` | | The ID of the [CatalogModifier](./models/catalog-modifier.md) whose default behavior is being overridden. | -| `on_by_default` | `Boolean` | Optional | If `true`, this [CatalogModifier](./models/catalog-modifier.md) should be selected by default for this [CatalogItem](./models/catalog-item.md). | - -### Example (as JSON) - -```json -{ - "modifier_id": "modifier_id2", - "on_by_default": null -} -``` - +## Catalog Modifier Override + +### Structure + +`CatalogModifierOverride` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `modifier_id` | `String` | | The ID of the [CatalogModifier](#type-catalogmodifier) whose default behavior is being overridden. | +| `on_by_default` | `Boolean` | Optional | If `true`, this [CatalogModifier](#type-catalogmodifier) should be selected by default for this [CatalogItem](#type-catalogitem). | + +### Example (as JSON) + +```json +{ + "modifier_id": "modifier_id2", + "on_by_default": null +} +``` + diff --git a/doc/models/catalog-modifier.md b/doc/models/catalog-modifier.md index c69331d2..f66cff10 100644 --- a/doc/models/catalog-modifier.md +++ b/doc/models/catalog-modifier.md @@ -1,33 +1,33 @@ -## Catalog Modifier - -A modifier in the Catalog object model. - -### Structure - -`CatalogModifier` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The modifier's name. Searchable. This field has max length of 255 Unicode code points. | -| `price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "object": { - "type": "MODIFIER", - "present_at_all_locations": true, - "modifier_data": { - "name": "Almond Milk", - "price_money": { - "amount": 250, - "currency": "USD" - } - } - } -} -``` - +## Catalog Modifier + +A modifier in the Catalog object model. + +### Structure + +`CatalogModifier` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The modifier's name. Searchable. This field has max length of 255 Unicode code points. | +| `price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "object": { + "type": "MODIFIER", + "present_at_all_locations": true, + "modifier_data": { + "name": "Almond Milk", + "price_money": { + "amount": 250, + "currency": "USD" + } + } + } +} +``` + diff --git a/doc/models/catalog-object-batch.md b/doc/models/catalog-object-batch.md index 6d270fc0..1b4997df 100644 --- a/doc/models/catalog-object-batch.md +++ b/doc/models/catalog-object-batch.md @@ -1,22 +1,22 @@ -## Catalog Object Batch - -A batch of [CatalogObject](./models/catalog-object.md)s. - -### Structure - -`CatalogObjectBatch` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `objects` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](./models/catalog-object.md)s belonging to this batch. | - -### Example (as JSON) - -```json -{ - "objects": null -} -``` - +## Catalog Object Batch + +A batch of [CatalogObject](#type-catalogobject)s. + +### Structure + +`CatalogObjectBatch` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `objects` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](#type-catalogobject)s belonging to this batch. | + +### Example (as JSON) + +```json +{ + "objects": null +} +``` + diff --git a/doc/models/catalog-object-type.md b/doc/models/catalog-object-type.md index d252f4b3..c9c634d2 100644 --- a/doc/models/catalog-object-type.md +++ b/doc/models/catalog-object-type.md @@ -1,28 +1,28 @@ -## Catalog Object Type - -Possible kinds of [CatalogObject](./models/catalog-object.md)s returned from the Catalog, each -containing type-specific properties in the `*_data` field corresponding to the object type. - -### Enumeration - -`CatalogObjectType` - -### Fields - -| Name | Description | -| --- | --- | -| `ITEM` | An item, corresponding to [CatalogItem](./models/catalog-item.md). The item-specific data
will be stored in the `item_data` field. | -| `IMAGE` | An image, corresponding to [CatalogImage](./models/catalog-image.md). The image-specific data
will be stored in the `image_data` field. | -| `CATEGORY` | A category, corresponding to [CatalogCategory](./models/catalog-category.md). The category-specific data
will be stored in the `category_data` field. | -| `ITEM_VARIATION` | An item variation, corresponding to [CatalogItemVariation](./models/catalog-item-variation.md). The
item variation-specific data will be stored in the `item_variation_data` field. | -| `TAX` | A tax, corresponding to [CatalogTax](./models/catalog-tax.md). The tax-specific data
will be stored in the `tax_data` field. | -| `DISCOUNT` | A discount, corresponding to [CatalogDiscount](./models/catalog-discount.md). The discount-specific data
will be stored in the `discount_data` field. | -| `MODIFIER_LIST` | A modifier list, corresponding to [CatalogModifierList](./models/catalog-modifier-list.md).
The modifier list-specific data will be stored in the `modifier_list_data` field. | -| `MODIFIER` | A modifier, corresponding to [CatalogModifier](./models/catalog-modifier.md). The modifier-specific data
will be stored in the `modifier_data` field. | -| `PRICING_RULE` | A pricing rule, corresponding to [CatalogPricingRule](./models/catalog-pricing-rule.md). The pricing-rule-specific data
will be stored in the `pricing_rule_data` field. | -| `PRODUCT_SET` | A product set, corresponding to [CatalogProductSet](./models/catalog-product-set.md).
The product-set-specific data will be stored in the `product_set_data` field. | -| `TIME_PERIOD` | A time period, corresponding to [CatalogTimePeriod](./models/catalog-time-period.md).
The time-period-specific data will be stored in the `time_period_data` field. | -| `MEASUREMENT_UNIT` | A measurement unit, corresponding to [CatalogMeasurementUnit](./models/catalog-measurement-unit.md). The unit of
measure and precision in which an item variation should be sold. | -| `ITEM_OPTION` | Represents a list of item option values that can be assigned to item
variations. For example, a color option or size option for a t-shirt. | -| `ITEM_OPTION_VAL` | Represents an option value associated with one or more item options.
For example, an item option of "Size" may have item option values such as
“Small" or "Medium". | - +## Catalog Object Type + +Possible kinds of [CatalogObject](#type-catalogobject)s returned from the Catalog, each +containing type-specific properties in the `*_data` field corresponding to the object type. + +### Enumeration + +`CatalogObjectType` + +### Fields + +| Name | Description | +| --- | --- | +| `ITEM` | An item, corresponding to [CatalogItem](#type-catalogitem). The item-specific data
will be stored in the `item_data` field. | +| `IMAGE` | An image, corresponding to [CatalogImage](#type-catalogimage). The image-specific data
will be stored in the `image_data` field. | +| `CATEGORY` | A category, corresponding to [CatalogCategory](#type-catalogcategory). The category-specific data
will be stored in the `category_data` field. | +| `ITEM_VARIATION` | An item variation, corresponding to [CatalogItemVariation](#type-catalogitemvariation). The
item variation-specific data will be stored in the `item_variation_data` field. | +| `TAX` | A tax, corresponding to [CatalogTax](#type-catalogtax). The tax-specific data
will be stored in the `tax_data` field. | +| `DISCOUNT` | A discount, corresponding to [CatalogDiscount](#type-catalogdiscount). The discount-specific data
will be stored in the `discount_data` field. | +| `MODIFIER_LIST` | A modifier list, corresponding to [CatalogModifierList](#type-catalogmodifierlist).
The modifier list-specific data will be stored in the `modifier_list_data` field. | +| `MODIFIER` | A modifier, corresponding to [CatalogModifier](#type-catalogmodifier). The modifier-specific data
will be stored in the `modifier_data` field. | +| `PRICING_RULE` | A pricing rule, corresponding to [CatalogPricingRule](#type-catalogpricingrule). The pricing-rule-specific data
will be stored in the `pricing_rule_data` field. | +| `PRODUCT_SET` | A product set, corresponding to [CatalogProductSet](#type-catalogproductset).
The product-set-specific data will be stored in the `product_set_data` field. | +| `TIME_PERIOD` | A time period, corresponding to [CatalogTimePeriod](#type-catalogtimeperiod).
The time-period-specific data will be stored in the `time_period_data` field. | +| `MEASUREMENT_UNIT` | A measurement unit, corresponding to [CatalogMeasurementUnit](#type-catalogmeasurementunit). The unit of
measure and precision in which an item variation should be sold. | +| `ITEM_OPTION` | Represents a list of item option values that can be assigned to item
variations. For example, a color option or size option for a t-shirt. | +| `ITEM_OPTION_VAL` | Represents an option value associated with one or more item options.
For example, an item option of "Size" may have item option values such as
“Small" or "Medium". | + diff --git a/doc/models/catalog-object.md b/doc/models/catalog-object.md index 55ab3b7a..e5c73403 100644 --- a/doc/models/catalog-object.md +++ b/doc/models/catalog-object.md @@ -1,82 +1,82 @@ -## Catalog Object - -The wrapper object for object types in the Catalog data model. The type -of a particular `CatalogObject` is determined by the value of -`type` and only the corresponding data field may be set. - -- if type = `ITEM`, only `item_data` will be populated and it will contain a valid [CatalogItem](./models/catalog-item.md) object. -- if type = `ITEM_VARIATION`, only `item_variation_data` will be populated and it will contain a valid [CatalogItemVariation](./models/catalog-item-variation.md) object. -- if type = `MODIFIER`, only `modifier_data` will be populated and it will contain a valid [CatalogModifier](./models/catalog-modifier.md) object. -- if type = `MODIFIER_LIST`, only `modifier_list_data` will be populated and it will contain a valid [CatalogModifierList](./models/catalog-modifier-list.md) object. -- if type = `CATEGORY`, only `category_data` will be populated and it will contain a valid [CatalogCategory](./models/catalog-category.md) object. -- if type = `DISCOUNT`, only `discount_data` will be populated and it will contain a valid [CatalogDiscount](./models/catalog-discount.md) object. -- if type = `TAX`, only `tax_data` will be populated and it will contain a valid [CatalogTax](./models/catalog-tax.md) object. -- if type = `IMAGE`, only `image_data` will be populated and it will contain a valid [CatalogImage](./models/catalog-image.md) object. - -For a more detailed discussion of the Catalog data model, please see the -[Design a Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog) guide. - -### Structure - -`CatalogObject` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `type` | [`String (Catalog Object Type)`](/doc/models/catalog-object-type.md) | | Possible kinds of [CatalogObject](./models/catalog-object.md)s returned from the Catalog, each
containing type-specific properties in the `*_data` field corresponding to the object type. | -| `id` | `String` | | An identifier to reference this object in the catalog. When a new CatalogObject
is inserted, the client should set the id to a temporary identifier starting with
a `'#'` character. Other objects being inserted or updated within the same request
may use this identifier to refer to the new object.

When the server receives the new object, it will supply a unique identifier that
replaces the temporary identifier for all future references. | -| `updated_at` | `String` | Optional | Last modification [timestamp](#workingwithdates) in RFC 3339 format, e.g., `"2016-08-15T23:59:33.123Z"`
would indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds. | -| `version` | `Long` | Optional | The version of the object. When updating an object, the version supplied
must match the version in the database, otherwise the write will be rejected as conflicting. | -| `is_deleted` | `Boolean` | Optional | If `true`, the object has been deleted from the database. Must be `false` for new objects
being inserted. When deleted, the `updated_at` field will equal the deletion time. | -| `catalog_v1_ids` | [`Array`](/doc/models/catalog-v1-id.md) | Optional | The Connect V1 IDs for this object at each [location](./models/location.md) where it is present, where they
differ from the object's Connect V2 ID. The field will only be present for objects that
have been created or modified by legacy APIs. | -| `present_at_all_locations` | `Boolean` | Optional | If `true`, this object is present at all locations (including future locations), except where specified in
the `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations),
except where specified in the `present_at_location_ids` field. If not specified, defaults to `true`. | -| `present_at_location_ids` | `Array` | Optional | A list of locations where the object is present, even if `present_at_all_locations` is `false`. | -| `absent_at_location_ids` | `Array` | Optional | A list of locations where the object is not present, even if `present_at_all_locations` is `true`. | -| `image_id` | `String` | Optional | Identifies the `CatalogImage` attached to this `CatalogObject`. | -| `item_data` | [`Catalog Item Hash`](/doc/models/catalog-item.md) | Optional | An item (i.e., product family) in the Catalog object model. | -| `category_data` | [`Catalog Category Hash`](/doc/models/catalog-category.md) | Optional | A category to which an [CatalogItem](./models/catalog-item.md) belongs in the Catalog object model. | -| `item_variation_data` | [`Catalog Item Variation Hash`](/doc/models/catalog-item-variation.md) | Optional | An item variation (i.e., product) in the Catalog object model. Each item
may have a maximum of 250 item variations. | -| `tax_data` | [`Catalog Tax Hash`](/doc/models/catalog-tax.md) | Optional | A tax in the Catalog object model. | -| `discount_data` | [`Catalog Discount Hash`](/doc/models/catalog-discount.md) | Optional | A discount in the Catalog object model. | -| `modifier_list_data` | [`Catalog Modifier List Hash`](/doc/models/catalog-modifier-list.md) | Optional | A modifier list in the Catalog object model. A [CatalogModifierList](./models/catalog-modifier-list.md)
contains [Modifier](./models/modifier.md)s that can be applied to a [CatalogItem](./models/catalog-item.md)
at the time of sale.

For example, a modifier list "Condiments" that would apply to a "Hot Dog" [CatalogItem](./models/catalog-item.md) might
contain [CatalogModifier](./models/catalog-modifier.md)s "Ketchup", "Mustard", and "Relish". The
`selection_type` field specifies whether or not multiple selections from the modifier list are allowed. | -| `modifier_data` | [`Catalog Modifier Hash`](/doc/models/catalog-modifier.md) | Optional | A modifier in the Catalog object model. | -| `time_period_data` | [`Catalog Time Period Hash`](/doc/models/catalog-time-period.md) | Optional | Represents a time period - either a single period or a repeating period. | -| `product_set_data` | [`Catalog Product Set Hash`](/doc/models/catalog-product-set.md) | Optional | Represents a collection of catalog objects for the purpose of applying a
[PricingRule](./models/pricing-rule.md). Including a catalog object will include all of
its subtypes. For example, including a category in a product set will include
all of its items and associated item variations in the product set. Including
an item in a product set will also include its item variations. | -| `pricing_rule_data` | [`Catalog Pricing Rule Hash`](/doc/models/catalog-pricing-rule.md) | Optional | Defines how prices are modified or set for items that match the pricing rule
during the active time period. | -| `image_data` | [`Catalog Image Hash`](/doc/models/catalog-image.md) | Optional | An image file to use in Square catalogs. Can be associated with catalog
items, item variations, and categories. | -| `measurement_unit_data` | [`Catalog Measurement Unit Hash`](/doc/models/catalog-measurement-unit.md) | Optional | Represents the unit used to measure a
[CatalogItemVariation](./models/catalog-item-variation.md) and specifies the precision
for decimal quantities. | -| `item_option_data` | [`Catalog Item Option Hash`](/doc/models/catalog-item-option.md) | Optional | A group of variations for a [CatalogItem](./models/catalog-item.md)'s. | -| `item_option_value_data` | [`Catalog Item Option Value Hash`](/doc/models/catalog-item-option-value.md) | Optional | An enumerated value that can link a
[CatalogItemVariation(#type-catalogitemvariation) to an item option as one of
its item option values. | - -### Example (as JSON) - -```json -{ - "type": "ITEM_OPTION", - "id": "id0", - "updated_at": null, - "version": null, - "is_deleted": null, - "catalog_v1_ids": null, - "present_at_all_locations": null, - "present_at_location_ids": null, - "absent_at_location_ids": null, - "image_id": null, - "item_data": null, - "category_data": null, - "item_variation_data": null, - "tax_data": null, - "discount_data": null, - "modifier_list_data": null, - "modifier_data": null, - "time_period_data": null, - "product_set_data": null, - "pricing_rule_data": null, - "image_data": null, - "measurement_unit_data": null, - "item_option_data": null, - "item_option_value_data": null -} -``` - +## Catalog Object + +The wrapper object for object types in the Catalog data model. The type +of a particular `CatalogObject` is determined by the value of +`type` and only the corresponding data field may be set. + +- if type = `ITEM`, only `item_data` will be populated and it will contain a valid [CatalogItem](#type-catalogitem) object. +- if type = `ITEM_VARIATION`, only `item_variation_data` will be populated and it will contain a valid [CatalogItemVariation](#type-catalogitemvariation) object. +- if type = `MODIFIER`, only `modifier_data` will be populated and it will contain a valid [CatalogModifier](#type-catalogmodifier) object. +- if type = `MODIFIER_LIST`, only `modifier_list_data` will be populated and it will contain a valid [CatalogModifierList](#type-catalogmodifierlist) object. +- if type = `CATEGORY`, only `category_data` will be populated and it will contain a valid [CatalogCategory](#type-catalogcategory) object. +- if type = `DISCOUNT`, only `discount_data` will be populated and it will contain a valid [CatalogDiscount](#type-catalogdiscount) object. +- if type = `TAX`, only `tax_data` will be populated and it will contain a valid [CatalogTax](#type-catalogtax) object. +- if type = `IMAGE`, only `image_data` will be populated and it will contain a valid [CatalogImage](#type-catalogimage) object. + +For a more detailed discussion of the Catalog data model, please see the +[Design a Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog) guide. + +### Structure + +`CatalogObject` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `type` | [`String (Catalog Object Type)`](/doc/models/catalog-object-type.md) | | Possible kinds of [CatalogObject](#type-catalogobject)s returned from the Catalog, each
containing type-specific properties in the `*_data` field corresponding to the object type. | +| `id` | `String` | | An identifier to reference this object in the catalog. When a new CatalogObject
is inserted, the client should set the id to a temporary identifier starting with
a `'#'` character. Other objects being inserted or updated within the same request
may use this identifier to refer to the new object.

When the server receives the new object, it will supply a unique identifier that
replaces the temporary identifier for all future references. | +| `updated_at` | `String` | Optional | Last modification [timestamp](#workingwithdates) in RFC 3339 format, e.g., `"2016-08-15T23:59:33.123Z"`
would indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds. | +| `version` | `Long` | Optional | The version of the object. When updating an object, the version supplied
must match the version in the database, otherwise the write will be rejected as conflicting. | +| `is_deleted` | `Boolean` | Optional | If `true`, the object has been deleted from the database. Must be `false` for new objects
being inserted. When deleted, the `updated_at` field will equal the deletion time. | +| `catalog_v1_ids` | [`Array`](/doc/models/catalog-v1-id.md) | Optional | The Connect V1 IDs for this object at each [location](#type-location) where it is present, where they
differ from the object's Connect V2 ID. The field will only be present for objects that
have been created or modified by legacy APIs. | +| `present_at_all_locations` | `Boolean` | Optional | If `true`, this object is present at all locations (including future locations), except where specified in
the `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations),
except where specified in the `present_at_location_ids` field. If not specified, defaults to `true`. | +| `present_at_location_ids` | `Array` | Optional | A list of locations where the object is present, even if `present_at_all_locations` is `false`. | +| `absent_at_location_ids` | `Array` | Optional | A list of locations where the object is not present, even if `present_at_all_locations` is `true`. | +| `image_id` | `String` | Optional | Identifies the `CatalogImage` attached to this `CatalogObject`. | +| `item_data` | [`Catalog Item Hash`](/doc/models/catalog-item.md) | Optional | An item (i.e., product family) in the Catalog object model. | +| `category_data` | [`Catalog Category Hash`](/doc/models/catalog-category.md) | Optional | A category to which an [CatalogItem](#type-catalogitem) belongs in the Catalog object model. | +| `item_variation_data` | [`Catalog Item Variation Hash`](/doc/models/catalog-item-variation.md) | Optional | An item variation (i.e., product) in the Catalog object model. Each item
may have a maximum of 250 item variations. | +| `tax_data` | [`Catalog Tax Hash`](/doc/models/catalog-tax.md) | Optional | A tax in the Catalog object model. | +| `discount_data` | [`Catalog Discount Hash`](/doc/models/catalog-discount.md) | Optional | A discount in the Catalog object model. | +| `modifier_list_data` | [`Catalog Modifier List Hash`](/doc/models/catalog-modifier-list.md) | Optional | A modifier list in the Catalog object model. A [CatalogModifierList](#type-catalogmodifierlist)
contains [Modifier](#type-catalogmodifier)s that can be applied to a [CatalogItem](#type-catalogitem)
at the time of sale.

For example, a modifier list "Condiments" that would apply to a "Hot Dog" [CatalogItem](#type-catalogitem) might
contain [CatalogModifier](#type-catalogmodifier)s "Ketchup", "Mustard", and "Relish". The
`selection_type` field specifies whether or not multiple selections from the modifier list are allowed. | +| `modifier_data` | [`Catalog Modifier Hash`](/doc/models/catalog-modifier.md) | Optional | A modifier in the Catalog object model. | +| `time_period_data` | [`Catalog Time Period Hash`](/doc/models/catalog-time-period.md) | Optional | Represents a time period - either a single period or a repeating period. | +| `product_set_data` | [`Catalog Product Set Hash`](/doc/models/catalog-product-set.md) | Optional | Represents a collection of catalog objects for the purpose of applying a
[PricingRule](#type-pricingrule). Including a catalog object will include all of
its subtypes. For example, including a category in a product set will include
all of its items and associated item variations in the product set. Including
an item in a product set will also include its item variations. | +| `pricing_rule_data` | [`Catalog Pricing Rule Hash`](/doc/models/catalog-pricing-rule.md) | Optional | Defines how prices are modified or set for items that match the pricing rule
during the active time period. | +| `image_data` | [`Catalog Image Hash`](/doc/models/catalog-image.md) | Optional | An image file to use in Square catalogs. Can be associated with catalog
items, item variations, and categories. | +| `measurement_unit_data` | [`Catalog Measurement Unit Hash`](/doc/models/catalog-measurement-unit.md) | Optional | Represents the unit used to measure a
[CatalogItemVariation](#type-catalogitemvariation) and specifies the precision
for decimal quantities. | +| `item_option_data` | [`Catalog Item Option Hash`](/doc/models/catalog-item-option.md) | Optional | A group of variations for a [CatalogItem](#type-catalogitem)'s. | +| `item_option_value_data` | [`Catalog Item Option Value Hash`](/doc/models/catalog-item-option-value.md) | Optional | An enumerated value that can link a
[CatalogItemVariation(#type-catalogitemvariation) to an item option as one of
its item option values. | + +### Example (as JSON) + +```json +{ + "type": "ITEM_OPTION", + "id": "id0", + "updated_at": null, + "version": null, + "is_deleted": null, + "catalog_v1_ids": null, + "present_at_all_locations": null, + "present_at_location_ids": null, + "absent_at_location_ids": null, + "image_id": null, + "item_data": null, + "category_data": null, + "item_variation_data": null, + "tax_data": null, + "discount_data": null, + "modifier_list_data": null, + "modifier_data": null, + "time_period_data": null, + "product_set_data": null, + "pricing_rule_data": null, + "image_data": null, + "measurement_unit_data": null, + "item_option_data": null, + "item_option_value_data": null +} +``` + diff --git a/doc/models/catalog-pricing-rule.md b/doc/models/catalog-pricing-rule.md index 57fb66c6..0bc1a83f 100644 --- a/doc/models/catalog-pricing-rule.md +++ b/doc/models/catalog-pricing-rule.md @@ -1,41 +1,41 @@ -## Catalog Pricing Rule - +## Catalog Pricing Rule + Defines how prices are modified or set for items that match the pricing rule -during the active time period. - -### Structure - -`CatalogPricingRule` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | User-defined name for the pricing rule. For example, "Buy one get one
free" or "10% off". | -| `time_period_ids` | `Array` | Optional | Unique ID for the [CatalogTimePeriod](./models/catalog-time-period.md)s when
this pricing rule is in effect. If left unset, the pricing rule is always
in effect. | -| `discount_id` | `String` | Optional | Unique ID for the [CatalogDiscount](./models/catalog-discount.md) to take off
the price of all matched items.

Only one of `total_price_money`, `item_price`, or `discount` can be supplied. | -| `match_products_id` | `String` | Optional | Unique ID for the [CatalogProductSet](./models/catalog-product-set.md) that will
be matched by this rule. A match rule matches within the entire cart. | -| `apply_products_id` | `String` | Optional | The [CatalogProductSet](./models/catalog-product-set.md) to apply the pricing rule to
within the set of matched products specified by `match_products_id`.
An apply rule can only match once within the set of matched products.
If left unset, the pricing rule will be applied to all products within the
set of matched products. | -| `exclude_products_id` | `String` | Optional | Identifies the [CatalogProductSet](./models/catalog-product-set.md) to exclude
from this pricing rule.
An exclude rule matches within the subset of the cart that fits the match rules (the match set).
An exclude rule can only match once in the match set.
If not supplied, the pricing will be applied to all products in the match set.
Other products retain their base price, or a price generated by other rules. | -| `valid_from_date` | `String` | Optional | Represents the date the Pricing Rule is valid from. Represented in
RFC3339 full-date format (YYYY-MM-DD). | -| `valid_from_local_time` | `String` | Optional | Represents the local time the pricing rule should be valid from. Time
zone is determined by the device running the Point of Sale app.

Represented in RFC3339 partial-time format (HH:MM:SS). Partial seconds will be truncated. | -| `valid_until_date` | `String` | Optional | Represents the date the pricing rule will become inactive.

Represented in RFC3339 full-date format (YYYY-MM-DD). | -| `valid_until_local_time` | `String` | Optional | Represents the local time at which the pricing rule will become inactive.
Time zone is determined by the device running the Point of Sale app.

Represented in RFC3339 partial-time format
(HH:MM:SS). Partial seconds will be truncated. | - -### Example (as JSON) - -```json -{ - "name": null, - "time_period_ids": null, - "discount_id": null, - "match_products_id": null, - "apply_products_id": null, - "exclude_products_id": null, - "valid_from_date": null, - "valid_from_local_time": null, - "valid_until_date": null, - "valid_until_local_time": null -} -``` - +during the active time period. + +### Structure + +`CatalogPricingRule` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | User-defined name for the pricing rule. For example, "Buy one get one
free" or "10% off". | +| `time_period_ids` | `Array` | Optional | Unique ID for the [CatalogTimePeriod](#type-catalogtimeperiod)s when
this pricing rule is in effect. If left unset, the pricing rule is always
in effect. | +| `discount_id` | `String` | Optional | Unique ID for the [CatalogDiscount](#type-catalogdiscount) to take off
the price of all matched items. | +| `match_products_id` | `String` | Optional | Unique ID for the [CatalogProductSet](#type-catalogproductset) that will
be matched by this rule. A match rule matches within the entire cart. | +| `apply_products_id` | `String` | Optional | The [CatalogProductSet](#type-catalogproductset) to apply the pricing rule to
within the set of matched products specified by `match_products_id`.
An apply rule can only match once within the set of matched products.
If left unset, the pricing rule will be applied to all products within the
set of matched products. | +| `exclude_products_id` | `String` | Optional | Identifies the [CatalogProductSet](#type-catalogproductset) to exclude
from this pricing rule.
An exclude rule matches within the subset of the cart that fits the match rules (the match set).
An exclude rule can only match once in the match set.
If not supplied, the pricing will be applied to all products in the match set.
Other products retain their base price, or a price generated by other rules. | +| `valid_from_date` | `String` | Optional | Represents the date the Pricing Rule is valid from. Represented in
RFC3339 full-date format (YYYY-MM-DD). | +| `valid_from_local_time` | `String` | Optional | Represents the local time the pricing rule should be valid from. Time
zone is determined by the device running the Point of Sale app.

Represented in RFC3339 partial-time format (HH:MM:SS). Partial seconds will be truncated. | +| `valid_until_date` | `String` | Optional | Represents the date the pricing rule will become inactive.

Represented in RFC3339 full-date format (YYYY-MM-DD). | +| `valid_until_local_time` | `String` | Optional | Represents the local time at which the pricing rule will become inactive.
Time zone is determined by the device running the Point of Sale app.

Represented in RFC3339 partial-time format
(HH:MM:SS). Partial seconds will be truncated. | + +### Example (as JSON) + +```json +{ + "name": null, + "time_period_ids": null, + "discount_id": null, + "match_products_id": null, + "apply_products_id": null, + "exclude_products_id": null, + "valid_from_date": null, + "valid_from_local_time": null, + "valid_until_date": null, + "valid_until_local_time": null +} +``` + diff --git a/doc/models/catalog-pricing-type.md b/doc/models/catalog-pricing-type.md index 556c2e5e..0bbec239 100644 --- a/doc/models/catalog-pricing-type.md +++ b/doc/models/catalog-pricing-type.md @@ -1,15 +1,15 @@ -## Catalog Pricing Type - -Indicates whether the price of a [CatalogItemVariation](./models/catalog-item-variation.md) should be entered manually at the time of sale. - -### Enumeration - -`CatalogPricingType` - -### Fields - -| Name | Description | -| --- | --- | -| `FIXED_PRICING` | The [CatalogItemVariation](./models/catalog-item-variation.md)'s price is fixed. | -| `VARIABLE_PRICING` | The [CatalogItemVariation](./models/catalog-item-variation.md)'s price is entered at the time of sale. | - +## Catalog Pricing Type + +Indicates whether the price of a [CatalogItemVariation](#type-catalogitemvariation) should be entered manually at the time of sale. + +### Enumeration + +`CatalogPricingType` + +### Fields + +| Name | Description | +| --- | --- | +| `FIXED_PRICING` | The [CatalogItemVariation](#type-catalogitemvariation)'s price is fixed. | +| `VARIABLE_PRICING` | The [CatalogItemVariation](#type-catalogitemvariation)'s price is entered at the time of sale. | + diff --git a/doc/models/catalog-product-set.md b/doc/models/catalog-product-set.md index 10791129..d6475a2c 100644 --- a/doc/models/catalog-product-set.md +++ b/doc/models/catalog-product-set.md @@ -1,38 +1,38 @@ -## Catalog Product Set - +## Catalog Product Set + Represents a collection of catalog objects for the purpose of applying a -[PricingRule](./models/pricing-rule.md). Including a catalog object will include all of +[PricingRule](#type-pricingrule). Including a catalog object will include all of its subtypes. For example, including a category in a product set will include all of its items and associated item variations in the product set. Including -an item in a product set will also include its item variations. - -### Structure - -`CatalogProductSet` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | User-defined name for the product set. For example, "Clearance Items"
or "Winter Sale Items". | -| `product_ids_any` | `Array` | Optional | Unique IDs for any [CatalogObjects](./models/catalog-objects.md)s to include in this
product set. Any number of these catalog objects can be in an order for a
pricing rule to apply.

This can be used with `product_ids_all` in a parent [CatalogProductSet](./models/catalog-product-set.md)
to match groups of products for a bulk discount, such as a discount for an entree and side combo.

Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.

Max: 500 catalog object IDs. | -| `product_ids_all` | `Array` | Optional | Unique IDs for [CatalogObjects](./models/catalog-objects.md) to include in this product set.
All objects in this set must be included in an order for a pricing rule to apply.

Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.

Max: 500 catalog object IDs. | -| `quantity_exact` | `Long` | Optional | If set, there must be exactly this many items from `products_any` or `products_all`
in the cart for the discount to apply.

Cannot be combined with either `quantity_min` or `quantity_max`. | -| `quantity_min` | `Long` | Optional | If set, there must be at least this many items from `products_any` or `products_all`
in a cart for the discount to apply. See `quantity_exact`. Defaults to 0 if
`quantity_exact`, `quantity_min` and
`quantity_max` are all unspecified. | -| `quantity_max` | `Long` | Optional | If set, the pricing rule will apply to a maximum of this many items from
`products_any` or `products_all`. | -| `all_products` | `Boolean` | Optional | If set to `true`, the product set will include every item in the catalog.

Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set. | - -### Example (as JSON) - -```json -{ - "name": null, - "product_ids_any": null, - "product_ids_all": null, - "quantity_exact": null, - "quantity_min": null, - "quantity_max": null, - "all_products": null -} -``` - +an item in a product set will also include its item variations. + +### Structure + +`CatalogProductSet` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | User-defined name for the product set. For example, "Clearance Items"
or "Winter Sale Items". | +| `product_ids_any` | `Array` | Optional | Unique IDs for any [CatalogObjects](#type-catalogobject)s to include in this
product set. Any number of these catalog objects can be in an order for a
pricing rule to apply.

This can be used with `product_ids_all` in a parent [CatalogProductSet](#type-catalogproductset)
to match groups of products for a bulk discount, such as a discount for an entree and side combo.

Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.

Max: 500 catalog object IDs. | +| `product_ids_all` | `Array` | Optional | Unique IDs for [CatalogObjects](#type-catalogobject) to include in this product set.
All objects in this set must be included in an order for a pricing rule to apply.

Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.

Max: 500 catalog object IDs. | +| `quantity_exact` | `Long` | Optional | If set, there must be exactly this many items from `products_any` or `products_all`
in the cart for the discount to apply.

Cannot be combined with either `quantity_min` or `quantity_max`. | +| `quantity_min` | `Long` | Optional | If set, there must be at least this many items from `products_any` or `products_all`
in a cart for the discount to apply. See `quantity_exact`. Defaults to 0 if
`quantity_exact`, `quantity_min` and
`quantity_max` are all unspecified. | +| `quantity_max` | `Long` | Optional | If set, the pricing rule will apply to a maximum of this many items from
`products_any` or `products_all`. | +| `all_products` | `Boolean` | Optional | If set to `true`, the product set will include every item in the catalog.

Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set. | + +### Example (as JSON) + +```json +{ + "name": null, + "product_ids_any": null, + "product_ids_all": null, + "quantity_exact": null, + "quantity_min": null, + "quantity_max": null, + "all_products": null +} +``` + diff --git a/doc/models/catalog-query-exact.md b/doc/models/catalog-query-exact.md index d9dda233..a796edc3 100644 --- a/doc/models/catalog-query-exact.md +++ b/doc/models/catalog-query-exact.md @@ -1,22 +1,22 @@ -## Catalog Query Exact - -### Structure - -`CatalogQueryExact` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `attribute_name` | `String` | The name of the attribute to be searched. | -| `attribute_value` | `String` | The desired value of the search attribute. | - -### Example (as JSON) - -```json -{ - "attribute_name": "attribute_name4", - "attribute_value": "attribute_value6" -} -``` - +## Catalog Query Exact + +### Structure + +`CatalogQueryExact` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `attribute_name` | `String` | The name of the attribute to be searched. | +| `attribute_value` | `String` | The desired value of the search attribute. | + +### Example (as JSON) + +```json +{ + "attribute_name": "attribute_name4", + "attribute_value": "attribute_value6" +} +``` + diff --git a/doc/models/catalog-query-item-variations-for-item-option-values.md b/doc/models/catalog-query-item-variations-for-item-option-values.md index c972f08f..5653c4dd 100644 --- a/doc/models/catalog-query-item-variations-for-item-option-values.md +++ b/doc/models/catalog-query-item-variations-for-item-option-values.md @@ -1,20 +1,20 @@ -## Catalog Query Item Variations for Item Option Values - -### Structure - -`CatalogQueryItemVariationsForItemOptionValues` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `item_option_value_ids` | `Array` | Optional | A set of [CatalogItemOptionValue](./models/catalog-item-option-value.md) IDs to be used to find associated
[CatalogItemVariation](./models/catalog-item-variation.md)s. All ItemVariations that contain all of the given
Item Option Values (in any order) will be returned. | - -### Example (as JSON) - -```json -{ - "item_option_value_ids": null -} -``` - +## Catalog Query Item Variations for Item Option Values + +### Structure + +`CatalogQueryItemVariationsForItemOptionValues` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `item_option_value_ids` | `Array` | Optional | A set of [CatalogItemOptionValue](#type-catalogitemoptionvalue) IDs to be used to find associated
[CatalogItemVariation](#type-catalogitemvariation)s. All ItemVariations that contain all of the given
Item Option Values (in any order) will be returned. | + +### Example (as JSON) + +```json +{ + "item_option_value_ids": null +} +``` + diff --git a/doc/models/catalog-query-items-for-item-options.md b/doc/models/catalog-query-items-for-item-options.md index 524a3b51..7c9d0738 100644 --- a/doc/models/catalog-query-items-for-item-options.md +++ b/doc/models/catalog-query-items-for-item-options.md @@ -1,20 +1,20 @@ -## Catalog Query Items for Item Options - -### Structure - -`CatalogQueryItemsForItemOptions` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `item_option_ids` | `Array` | Optional | A set of [CatalogItemOption](./models/catalog-item.mdoption) IDs to be used to find associated
[CatalogItem](./models/catalog-item.md)s. All Items that contain all of the given Item Options (in any order)
will be returned. | - -### Example (as JSON) - -```json -{ - "item_option_ids": null -} -``` - +## Catalog Query Items for Item Options + +### Structure + +`CatalogQueryItemsForItemOptions` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `item_option_ids` | `Array` | Optional | A set of [CatalogItemOption](#type-catalogitemoption) IDs to be used to find associated
[CatalogItem](#type-catalogitem)s. All Items that contain all of the given Item Options (in any order)
will be returned. | + +### Example (as JSON) + +```json +{ + "item_option_ids": null +} +``` + diff --git a/doc/models/catalog-query-items-for-modifier-list.md b/doc/models/catalog-query-items-for-modifier-list.md index b7278933..d1569c27 100644 --- a/doc/models/catalog-query-items-for-modifier-list.md +++ b/doc/models/catalog-query-items-for-modifier-list.md @@ -1,22 +1,22 @@ -## Catalog Query Items for Modifier List - -### Structure - -`CatalogQueryItemsForModifierList` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `modifier_list_ids` | `Array` | A set of [CatalogModifierList](./models/catalog-modifier-list.md) IDs to be used to find associated [CatalogItem](./models/catalog-item.md)s. | - -### Example (as JSON) - -```json -{ - "modifier_list_ids": [ - "modifier_list_ids0" - ] -} -``` - +## Catalog Query Items for Modifier List + +### Structure + +`CatalogQueryItemsForModifierList` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `modifier_list_ids` | `Array` | A set of [CatalogModifierList](#type-catalogmodifierlist) IDs to be used to find associated [CatalogItem](#type-catalogitem)s. | + +### Example (as JSON) + +```json +{ + "modifier_list_ids": [ + "modifier_list_ids0" + ] +} +``` + diff --git a/doc/models/catalog-query-items-for-tax.md b/doc/models/catalog-query-items-for-tax.md index bf604b80..caa535d7 100644 --- a/doc/models/catalog-query-items-for-tax.md +++ b/doc/models/catalog-query-items-for-tax.md @@ -1,22 +1,22 @@ -## Catalog Query Items for Tax - -### Structure - -`CatalogQueryItemsForTax` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `tax_ids` | `Array` | A set of [CatalogTax](./models/catalog-tax.md) IDs to be used to find associated [CatalogItem](./models/catalog-item.md)s. | - -### Example (as JSON) - -```json -{ - "tax_ids": [ - "tax_ids7" - ] -} -``` - +## Catalog Query Items for Tax + +### Structure + +`CatalogQueryItemsForTax` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `tax_ids` | `Array` | A set of [CatalogTax](#type-catalogtax) IDs to be used to find associated [CatalogItem](#type-catalogitem)s. | + +### Example (as JSON) + +```json +{ + "tax_ids": [ + "tax_ids7" + ] +} +``` + diff --git a/doc/models/catalog-query-prefix.md b/doc/models/catalog-query-prefix.md index df009781..8f59ca67 100644 --- a/doc/models/catalog-query-prefix.md +++ b/doc/models/catalog-query-prefix.md @@ -1,22 +1,22 @@ -## Catalog Query Prefix - -### Structure - -`CatalogQueryPrefix` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `attribute_name` | `String` | The name of the attribute to be searched. | -| `attribute_prefix` | `String` | The desired prefix of the search attribute value. | - -### Example (as JSON) - -```json -{ - "attribute_name": "attribute_name4", - "attribute_prefix": "attribute_prefix0" -} -``` - +## Catalog Query Prefix + +### Structure + +`CatalogQueryPrefix` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `attribute_name` | `String` | The name of the attribute to be searched. | +| `attribute_prefix` | `String` | The desired prefix of the search attribute value. | + +### Example (as JSON) + +```json +{ + "attribute_name": "attribute_name4", + "attribute_prefix": "attribute_prefix0" +} +``` + diff --git a/doc/models/catalog-query-range.md b/doc/models/catalog-query-range.md index b0b18d26..4af20de5 100644 --- a/doc/models/catalog-query-range.md +++ b/doc/models/catalog-query-range.md @@ -1,24 +1,24 @@ -## Catalog Query Range - -### Structure - -`CatalogQueryRange` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `attribute_name` | `String` | | The name of the attribute to be searched. | -| `attribute_min_value` | `Long` | Optional | The desired minimum value for the search attribute (inclusive). | -| `attribute_max_value` | `Long` | Optional | The desired maximum value for the search attribute (inclusive). | - -### Example (as JSON) - -```json -{ - "attribute_name": "attribute_name4", - "attribute_min_value": null, - "attribute_max_value": null -} -``` - +## Catalog Query Range + +### Structure + +`CatalogQueryRange` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `attribute_name` | `String` | | The name of the attribute to be searched. | +| `attribute_min_value` | `Long` | Optional | The desired minimum value for the search attribute (inclusive). | +| `attribute_max_value` | `Long` | Optional | The desired maximum value for the search attribute (inclusive). | + +### Example (as JSON) + +```json +{ + "attribute_name": "attribute_name4", + "attribute_min_value": null, + "attribute_max_value": null +} +``` + diff --git a/doc/models/catalog-query-sorted-attribute.md b/doc/models/catalog-query-sorted-attribute.md index 293ce9b6..30afac80 100644 --- a/doc/models/catalog-query-sorted-attribute.md +++ b/doc/models/catalog-query-sorted-attribute.md @@ -1,24 +1,24 @@ -## Catalog Query Sorted Attribute - -### Structure - -`CatalogQuerySortedAttribute` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `attribute_name` | `String` | | The attribute whose value should be used as the sort key. | -| `initial_attribute_value` | `String` | Optional | The first attribute value to be returned by the query. Ascending sorts will return only
objects with this value or greater, while descending sorts will return only objects with this value
or less. If unset, start at the beginning (for ascending sorts) or end (for descending sorts). | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | - -### Example (as JSON) - -```json -{ - "attribute_name": "attribute_name4", - "initial_attribute_value": null, - "sort_order": null -} -``` - +## Catalog Query Sorted Attribute + +### Structure + +`CatalogQuerySortedAttribute` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `attribute_name` | `String` | | The attribute whose value should be used as the sort key. | +| `initial_attribute_value` | `String` | Optional | The first attribute value to be returned by the query. Ascending sorts will return only
objects with this value or greater, while descending sorts will return only objects with this value
or less. If unset, start at the beginning (for ascending sorts) or end (for descending sorts). | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | + +### Example (as JSON) + +```json +{ + "attribute_name": "attribute_name4", + "initial_attribute_value": null, + "sort_order": null +} +``` + diff --git a/doc/models/catalog-query-text.md b/doc/models/catalog-query-text.md index 744be77c..1b5ae5ec 100644 --- a/doc/models/catalog-query-text.md +++ b/doc/models/catalog-query-text.md @@ -1,23 +1,23 @@ -## Catalog Query Text - -### Structure - -`CatalogQueryText` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `keywords` | `Array` | A list of one, two, or three search keywords. Keywords with fewer than three characters
are ignored. | - -### Example (as JSON) - -```json -{ - "keywords": [ - "keywords3", - "keywords4" - ] -} -``` - +## Catalog Query Text + +### Structure + +`CatalogQueryText` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `keywords` | `Array` | A list of one, two, or three search keywords. Keywords with fewer than three characters
are ignored. | + +### Example (as JSON) + +```json +{ + "keywords": [ + "keywords3", + "keywords4" + ] +} +``` + diff --git a/doc/models/catalog-query.md b/doc/models/catalog-query.md index d55528af..205ec0e4 100644 --- a/doc/models/catalog-query.md +++ b/doc/models/catalog-query.md @@ -1,50 +1,50 @@ -## Catalog Query - -A query to be applied to a [SearchCatalogObjectsRequest](./models/search-catalog-objects-request.md). -Only one query field may be present. - -Where an attribute name is required, it should be specified as the name of any field -marked "searchable" from the structured data types for the desired result object type(s) -([CatalogItem](./models/catalog-item.md), [CatalogItemVariation](./models/catalog-item-variation.md), -[CatalogCategory](./models/catalog-category.md), [CatalogTax](./models/catalog-tax.md), -[CatalogDiscount](./models/catalog-discount.md), [CatalogModifierList](./models/catalog-modifier-list.md), -[CatalogModifier](./models/catalog-modifier.md)). - -For example, a query that should return Items may specify attribute names from -any of the searchable fields of the [CatalogItem](./models/catalog-item.md) data type, namely -`"name"`, `"description"`, and `"abbreviation"`. - -### Structure - -`CatalogQuery` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `sorted_attribute_query` | [`Catalog Query Sorted Attribute Hash`](/doc/models/catalog-query-sorted-attribute.md) | Optional | - | -| `exact_query` | [`Catalog Query Exact Hash`](/doc/models/catalog-query-exact.md) | Optional | - | -| `prefix_query` | [`Catalog Query Prefix Hash`](/doc/models/catalog-query-prefix.md) | Optional | - | -| `range_query` | [`Catalog Query Range Hash`](/doc/models/catalog-query-range.md) | Optional | - | -| `text_query` | [`Catalog Query Text Hash`](/doc/models/catalog-query-text.md) | Optional | - | -| `items_for_tax_query` | [`Catalog Query Items for Tax Hash`](/doc/models/catalog-query-items-for-tax.md) | Optional | - | -| `items_for_modifier_list_query` | [`Catalog Query Items for Modifier List Hash`](/doc/models/catalog-query-items-for-modifier-list.md) | Optional | - | -| `items_for_item_options_query` | [`Catalog Query Items for Item Options Hash`](/doc/models/catalog-query-items-for-item-options.md) | Optional | - | -| `item_variations_for_item_option_values_query` | [`Catalog Query Item Variations for Item Option Values Hash`](/doc/models/catalog-query-item-variations-for-item-option-values.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "sorted_attribute_query": null, - "exact_query": null, - "prefix_query": null, - "range_query": null, - "text_query": null, - "items_for_tax_query": null, - "items_for_modifier_list_query": null, - "items_for_item_options_query": null, - "item_variations_for_item_option_values_query": null -} -``` - +## Catalog Query + +A query to be applied to a [SearchCatalogObjectsRequest](#type-searchcatalogobjectsrequest). +Only one query field may be present. + +Where an attribute name is required, it should be specified as the name of any field +marked "searchable" from the structured data types for the desired result object type(s) +([CatalogItem](#type-catalogitem), [CatalogItemVariation](#type-catalogitemvariation), +[CatalogCategory](#type-catalogcategory), [CatalogTax](#type-catalogtax), +[CatalogDiscount](#type-catalogdiscount), [CatalogModifierList](#type-catalogmodifierlist), +[CatalogModifier](#type-catalogmodifier)). + +For example, a query that should return Items may specify attribute names from +any of the searchable fields of the [CatalogItem](#type-catalogitem) data type, namely +`"name"`, `"description"`, and `"abbreviation"`. + +### Structure + +`CatalogQuery` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `sorted_attribute_query` | [`Catalog Query Sorted Attribute Hash`](/doc/models/catalog-query-sorted-attribute.md) | Optional | - | +| `exact_query` | [`Catalog Query Exact Hash`](/doc/models/catalog-query-exact.md) | Optional | - | +| `prefix_query` | [`Catalog Query Prefix Hash`](/doc/models/catalog-query-prefix.md) | Optional | - | +| `range_query` | [`Catalog Query Range Hash`](/doc/models/catalog-query-range.md) | Optional | - | +| `text_query` | [`Catalog Query Text Hash`](/doc/models/catalog-query-text.md) | Optional | - | +| `items_for_tax_query` | [`Catalog Query Items for Tax Hash`](/doc/models/catalog-query-items-for-tax.md) | Optional | - | +| `items_for_modifier_list_query` | [`Catalog Query Items for Modifier List Hash`](/doc/models/catalog-query-items-for-modifier-list.md) | Optional | - | +| `items_for_item_options_query` | [`Catalog Query Items for Item Options Hash`](/doc/models/catalog-query-items-for-item-options.md) | Optional | - | +| `item_variations_for_item_option_values_query` | [`Catalog Query Item Variations for Item Option Values Hash`](/doc/models/catalog-query-item-variations-for-item-option-values.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "sorted_attribute_query": null, + "exact_query": null, + "prefix_query": null, + "range_query": null, + "text_query": null, + "items_for_tax_query": null, + "items_for_modifier_list_query": null, + "items_for_item_options_query": null, + "item_variations_for_item_option_values_query": null +} +``` + diff --git a/doc/models/catalog-tax.md b/doc/models/catalog-tax.md index 7c9f0651..16380f8a 100644 --- a/doc/models/catalog-tax.md +++ b/doc/models/catalog-tax.md @@ -1,39 +1,39 @@ -## Catalog Tax - -A tax in the Catalog object model. - -### Structure - -`CatalogTax` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The tax's name. Searchable. This field has max length of 255 Unicode code points. | -| `calculation_phase` | [`String (Tax Calculation Phase)`](/doc/models/tax-calculation-phase.md) | Optional | When to calculate the taxes due on a cart. | -| `inclusion_type` | [`String (Tax Inclusion Type)`](/doc/models/tax-inclusion-type.md) | Optional | Whether to the tax amount should be additional to or included in to the [CatalogItem](./models/catalog-item.md) price. | -| `percentage` | `String` | Optional | The percentage of the tax in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign.
A value of `7.5` corresponds to 7.5%. | -| `applies_to_custom_amounts` | `Boolean` | Optional | If `true`, the fee applies to custom amounts entered into the Square Point of Sale
app that are not associated with a particular [CatalogItem](./models/catalog-item.md). | -| `enabled` | `Boolean` | Optional | If `true`, the tax will be shown as enabled in the Square Point of Sale app. | - -### Example (as JSON) - -```json -{ - "object": { - "type": "TAX", - "id": "#SalesTax", - "present_at_all_locations": true, - "tax_data": { - "name": "Sales Tax", - "calculation_phase": "TAX_SUBTOTAL_PHASE", - "inclusion_type": "ADDITIVE", - "percentage": "5.0", - "fee_applies_to_custom_amounts": true, - "enabled": true - } - } -} -``` - +## Catalog Tax + +A tax in the Catalog object model. + +### Structure + +`CatalogTax` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The tax's name. Searchable. This field has max length of 255 Unicode code points. | +| `calculation_phase` | [`String (Tax Calculation Phase)`](/doc/models/tax-calculation-phase.md) | Optional | When to calculate the taxes due on a cart. | +| `inclusion_type` | [`String (Tax Inclusion Type)`](/doc/models/tax-inclusion-type.md) | Optional | Whether to the tax amount should be additional to or included in to the [CatalogItem](#type-catalogitem) price. | +| `percentage` | `String` | Optional | The percentage of the tax in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign.
A value of `7.5` corresponds to 7.5%. | +| `applies_to_custom_amounts` | `Boolean` | Optional | If `true`, the fee applies to custom amounts entered into the Square Point of Sale
app that are not associated with a particular [CatalogItem](#type-catalogitem). | +| `enabled` | `Boolean` | Optional | If `true`, the tax will be shown as enabled in the Square Point of Sale app. | + +### Example (as JSON) + +```json +{ + "object": { + "type": "TAX", + "id": "#SalesTax", + "present_at_all_locations": true, + "tax_data": { + "name": "Sales Tax", + "calculation_phase": "TAX_SUBTOTAL_PHASE", + "inclusion_type": "ADDITIVE", + "percentage": "5.0", + "fee_applies_to_custom_amounts": true, + "enabled": true + } + } +} +``` + diff --git a/doc/models/catalog-time-period.md b/doc/models/catalog-time-period.md index 3ba1c600..9ea9e533 100644 --- a/doc/models/catalog-time-period.md +++ b/doc/models/catalog-time-period.md @@ -1,22 +1,22 @@ -## Catalog Time Period - -Represents a time period - either a single period or a repeating period. - -### Structure - -`CatalogTimePeriod` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `event` | `String` | Optional | An iCalendar (RFC5545) [event](https://tools.ietf.org/html/rfc5545#section-3.6.1), which
specifies the name, timing, duration and recurrence of this time period.

Example:

```
DTSTART:20190707T180000
DURATION:P2H
RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR
```

Only `SUMMARY`, `DTSTART`, `DURATION` and `RRULE` fields are supported.
`DTSTART` must be in local (unzoned) time format. Note that while `BEGIN:VEVENT`
and `END:VEVENT` is not required in the request. The response will always
include them. | - -### Example (as JSON) - -```json -{ - "event": null -} -``` - +## Catalog Time Period + +Represents a time period - either a single period or a repeating period. + +### Structure + +`CatalogTimePeriod` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `event` | `String` | Optional | An iCalendar (RFC5545) [event](https://tools.ietf.org/html/rfc5545#section-3.6.1), which
specifies the name, timing, duration and recurrence of this time period.

Example:

```
DTSTART:20190707T180000
DURATION:P2H
RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR
```

Only `SUMMARY`, `DTSTART`, `DURATION` and `RRULE` fields are supported.
`DTSTART` must be in local (unzoned) time format. Note that while `BEGIN:VEVENT`
and `END:VEVENT` is not required in the request. The response will always
include them. | + +### Example (as JSON) + +```json +{ + "event": null +} +``` + diff --git a/doc/models/catalog-v1-id.md b/doc/models/catalog-v1-id.md index 3388d387..4f41abf7 100644 --- a/doc/models/catalog-v1-id.md +++ b/doc/models/catalog-v1-id.md @@ -1,24 +1,24 @@ -## Catalog V1 Id - -An Items Connect V1 object ID along with its associated [location](./models/location.md) ID. - -### Structure - -`CatalogV1Id` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `catalog_v1_id` | `String` | Optional | The ID for an object in Connect V1, if different from its Connect V2 ID. | -| `location_id` | `String` | Optional | The ID of the [location](./models/location.md) this Connect V1 ID is associated with. | - -### Example (as JSON) - -```json -{ - "catalog_v1_id": null, - "location_id": null -} -``` - +## Catalog V1 Id + +An Items Connect V1 object ID along with its associated [location](#type-location) ID. + +### Structure + +`CatalogV1Id` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `catalog_v1_id` | `String` | Optional | The ID for an object in Connect V1, if different from its Connect V2 ID. | +| `location_id` | `String` | Optional | The ID of the [location](#type-location) this Connect V1 ID is associated with. | + +### Example (as JSON) + +```json +{ + "catalog_v1_id": null, + "location_id": null +} +``` + diff --git a/doc/models/charge-request-additional-recipient.md b/doc/models/charge-request-additional-recipient.md index 37e40918..cbdd2ecf 100644 --- a/doc/models/charge-request-additional-recipient.md +++ b/doc/models/charge-request-additional-recipient.md @@ -1,30 +1,30 @@ -## Charge Request Additional Recipient - -Represents an additional recipient (other than the merchant) entitled to a portion of the tender. -Support is currently limited to USD, CAD and GBP currencies - -### Structure - -`ChargeRequestAdditionalRecipient` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `location_id` | `String` | The location ID for a recipient (other than the merchant) receiving a portion of the tender. | -| `description` | `String` | The description of the additional recipient. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "location_id": "location_id4", - "description": "description0", - "amount_money": { - "amount": null, - "currency": null - } -} -``` - +## Charge Request Additional Recipient + +Represents an additional recipient (other than the merchant) entitled to a portion of the tender. +Support is currently limited to USD, CAD and GBP currencies + +### Structure + +`ChargeRequestAdditionalRecipient` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `location_id` | `String` | The location ID for a recipient (other than the merchant) receiving a portion of the tender. | +| `description` | `String` | The description of the additional recipient. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "location_id": "location_id4", + "description": "description0", + "amount_money": { + "amount": null, + "currency": null + } +} +``` + diff --git a/doc/models/charge-request.md b/doc/models/charge-request.md index 97bb016d..22d14702 100644 --- a/doc/models/charge-request.md +++ b/doc/models/charge-request.md @@ -1,71 +1,71 @@ -## Charge Request - -Defines the parameters that can be included in the body of -a request to the [Charge](#endpoint-charge) endpoint. - -Deprecated - recommend using [CreatePayment](/doc/payments.md#createpayment) - -### Structure - -`ChargeRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `idempotency_key` | `String` | | A value you specify that uniquely identifies this
transaction among transactions you've created.

If you're unsure whether a particular transaction succeeded,
you can reattempt it with the same idempotency key without
worrying about double-charging the buyer.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `card_nonce` | `String` | Optional | A nonce generated from the `SqPaymentForm` that represents the card
to charge.

The application that provides a nonce to this endpoint must be the
_same application_ that generated the nonce with the `SqPaymentForm`.
Otherwise, the nonce is invalid.

Do not provide a value for this field if you provide a value for
`customer_card_id`. | -| `customer_card_id` | `String` | Optional | The ID of the customer card on file to charge. Do
not provide a value for this field if you provide a value for `card_nonce`.

If you provide this value, you _must_ also provide a value for
`customer_id`. | -| `delay_capture` | `Boolean` | Optional | If `true`, the request will only perform an Auth on the provided
card. You can then later perform either a Capture (with the
[CaptureTransaction](#endpoint-capturetransaction) endpoint) or a Void
(with the [VoidTransaction](#endpoint-voidtransaction) endpoint).

Default value: `false` | -| `reference_id` | `String` | Optional | An optional ID you can associate with the transaction for your own
purposes (such as to associate the transaction with an entity ID in your
own database).

This value cannot exceed 40 characters. | -| `note` | `String` | Optional | An optional note to associate with the transaction.

This value cannot exceed 60 characters. | -| `customer_id` | `String` | Optional | The ID of the customer to associate this transaction with. This field
is required if you provide a value for `customer_card_id`, and optional
otherwise. | -| `billing_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `buyer_email_address` | `String` | Optional | The buyer's email address, if available. | -| `order_id` | `String` | Optional | The ID of the order to associate with this transaction.

If you provide this value, the `amount_money` value of your request must
__exactly match__ the value of the order's `total_money` field. | -| `additional_recipients` | [`Array`](/doc/models/additional-recipient.md) | Optional | The basic primitive of multi-party transaction. The value is optional.
The transaction facilitated by you can be split from here.

If you provide this value, the `amount_money` value in your additional_recipients
must not be more than 90% of the `amount_money` value in the charge request.
The `location_id` must be the valid location of the app owner merchant.

This field requires the `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission.

This field is currently not supported in sandbox. | -| `verification_token` | `String` | Optional | An identifying token generated by `SqPaymentForm.verifyBuyer()`.
Verification tokens encapsulate customer device information and 3-D Secure
challenge results to indicate that Square has verified the buyer identity. | - -### Example (as JSON) - -```json -{ - "idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13", - "shipping_address": { - "address_line_1": "123 Main St", - "locality": "San Francisco", - "administrative_district_level_1": "CA", - "postal_code": "94114", - "country": "US" - }, - "billing_address": { - "address_line_1": "500 Electric Ave", - "address_line_2": "Suite 600", - "administrative_district_level_1": "NY", - "locality": "New York", - "postal_code": "10003", - "country": "US" - }, - "amount_money": { - "amount": 200, - "currency": "USD" - }, - "additional_recipients": [ - { - "location_id": "057P5VYJ4A5X1", - "description": "Application fees", - "amount_money": { - "amount": 20, - "currency": "USD" - } - } - ], - "card_nonce": "card_nonce_from_square_123", - "reference_id": "some optional reference id", - "note": "some optional note", - "delay_capture": false -} -``` - +## Charge Request + +Defines the parameters that can be included in the body of +a request to the [Charge](#endpoint-charge) endpoint. + +Deprecated - recommend using [CreatePayment](#endpoint-payments-createpayment) + +### Structure + +`ChargeRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `String` | | A value you specify that uniquely identifies this
transaction among transactions you've created.

If you're unsure whether a particular transaction succeeded,
you can reattempt it with the same idempotency key without
worrying about double-charging the buyer.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `card_nonce` | `String` | Optional | A nonce generated from the `SqPaymentForm` that represents the card
to charge.

The application that provides a nonce to this endpoint must be the
_same application_ that generated the nonce with the `SqPaymentForm`.
Otherwise, the nonce is invalid.

Do not provide a value for this field if you provide a value for
`customer_card_id`. | +| `customer_card_id` | `String` | Optional | The ID of the customer card on file to charge. Do
not provide a value for this field if you provide a value for `card_nonce`.

If you provide this value, you _must_ also provide a value for
`customer_id`. | +| `delay_capture` | `Boolean` | Optional | If `true`, the request will only perform an Auth on the provided
card. You can then later perform either a Capture (with the
[CaptureTransaction](#endpoint-capturetransaction) endpoint) or a Void
(with the [VoidTransaction](#endpoint-voidtransaction) endpoint).

Default value: `false` | +| `reference_id` | `String` | Optional | An optional ID you can associate with the transaction for your own
purposes (such as to associate the transaction with an entity ID in your
own database).

This value cannot exceed 40 characters. | +| `note` | `String` | Optional | An optional note to associate with the transaction.

This value cannot exceed 60 characters. | +| `customer_id` | `String` | Optional | The ID of the customer to associate this transaction with. This field
is required if you provide a value for `customer_card_id`, and optional
otherwise. | +| `billing_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `buyer_email_address` | `String` | Optional | The buyer's email address, if available. | +| `order_id` | `String` | Optional | The ID of the order to associate with this transaction.

If you provide this value, the `amount_money` value of your request must
__exactly match__ the value of the order's `total_money` field. | +| `additional_recipients` | [`Array`](/doc/models/additional-recipient.md) | Optional | The basic primitive of multi-party transaction. The value is optional.
The transaction facilitated by you can be split from here.

If you provide this value, the `amount_money` value in your additional_recipients
must not be more than 90% of the `amount_money` value in the charge request.
The `location_id` must be the valid location of the app owner merchant.

This field requires the `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission.

This field is currently not supported in sandbox. | +| `verification_token` | `String` | Optional | An identifying token generated by `SqPaymentForm.verifyBuyer()`.
Verification tokens encapsulate customer device information and 3-D Secure
challenge results to indicate that Square has verified the buyer identity. | + +### Example (as JSON) + +```json +{ + "idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13", + "shipping_address": { + "address_line_1": "123 Main St", + "locality": "San Francisco", + "administrative_district_level_1": "CA", + "postal_code": "94114", + "country": "US" + }, + "billing_address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "administrative_district_level_1": "NY", + "locality": "New York", + "postal_code": "10003", + "country": "US" + }, + "amount_money": { + "amount": 200, + "currency": "USD" + }, + "additional_recipients": [ + { + "location_id": "057P5VYJ4A5X1", + "description": "Application fees", + "amount_money": { + "amount": 20, + "currency": "USD" + } + } + ], + "card_nonce": "card_nonce_from_square_123", + "reference_id": "some optional reference id", + "note": "some optional note", + "delay_capture": false +} +``` + diff --git a/doc/models/charge-response.md b/doc/models/charge-response.md index 77038bf0..08f3a49e 100644 --- a/doc/models/charge-response.md +++ b/doc/models/charge-response.md @@ -1,65 +1,65 @@ -## Charge Response - -Defines the fields that are included in the response body of -a request to the [Charge](#endpoint-charge) endpoint. - -One of `errors` or `transaction` is present in a given response (never both). - -### Structure - -`ChargeResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `transaction` | [`Transaction Hash`](/doc/models/transaction.md) | Optional | Represents a transaction processed with Square, either with the
Connect API or with Square Point of Sale.

The `tenders` field of this object lists all methods of payment used to pay in
the transaction. | - -### Example (as JSON) - -```json -{ - "transaction": { - "id": "KnL67ZIwXCPtzOrqj0HrkxMF", - "location_id": "18YC4JDH91E1H", - "created_at": "2016-03-10T22:57:56Z", - "tenders": [ - { - "id": "MtZRYYdDrYNQbOvV7nbuBvMF", - "location_id": "18YC4JDH91E1H", - "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", - "created_at": "2016-03-10T22:57:56Z", - "note": "some optional note", - "amount_money": { - "amount": 200, - "currency": "USD" - }, - "additional_recipients": [ - { - "location_id": "057P5VYJ4A5X1", - "description": "Application fees", - "amount_money": { - "amount": 20, - "currency": "USD" - }, - "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF" - } - ], - "type": "CARD", - "card_details": { - "status": "CAPTURED", - "card": { - "card_brand": "VISA", - "last_4": "1111" - }, - "entry_method": "KEYED" - } - } - ], - "reference_id": "some optional reference id", - "product": "EXTERNAL_API" - } -} -``` - +## Charge Response + +Defines the fields that are included in the response body of +a request to the [Charge](#endpoint-charge) endpoint. + +One of `errors` or `transaction` is present in a given response (never both). + +### Structure + +`ChargeResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `transaction` | [`Transaction Hash`](/doc/models/transaction.md) | Optional | Represents a transaction processed with Square, either with the
Connect API or with Square Point of Sale.

The `tenders` field of this object lists all methods of payment used to pay in
the transaction. | + +### Example (as JSON) + +```json +{ + "transaction": { + "id": "KnL67ZIwXCPtzOrqj0HrkxMF", + "location_id": "18YC4JDH91E1H", + "created_at": "2016-03-10T22:57:56Z", + "tenders": [ + { + "id": "MtZRYYdDrYNQbOvV7nbuBvMF", + "location_id": "18YC4JDH91E1H", + "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", + "created_at": "2016-03-10T22:57:56Z", + "note": "some optional note", + "amount_money": { + "amount": 200, + "currency": "USD" + }, + "additional_recipients": [ + { + "location_id": "057P5VYJ4A5X1", + "description": "Application fees", + "amount_money": { + "amount": 20, + "currency": "USD" + }, + "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF" + } + ], + "type": "CARD", + "card_details": { + "status": "CAPTURED", + "card": { + "card_brand": "VISA", + "last_4": "1111" + }, + "entry_method": "KEYED" + } + } + ], + "reference_id": "some optional reference id", + "product": "EXTERNAL_API" + } +} +``` + diff --git a/doc/models/checkout.md b/doc/models/checkout.md index 4b173473..e9f7ab56 100644 --- a/doc/models/checkout.md +++ b/doc/models/checkout.md @@ -1,41 +1,41 @@ -## Checkout - -Square Checkout lets merchants accept online payments for supported -payment types using a checkout workflow hosted on squareup.com. - -### Structure - -`Checkout` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | ID generated by Square Checkout when a new checkout is requested. | -| `checkout_page_url` | `String` | Optional | The URL that the buyer's browser should be redirected to after the
checkout is completed. | -| `ask_for_shipping_address` | `Boolean` | Optional | If `true`, Square Checkout will collect shipping information on your
behalf and store that information with the transaction information in your
Square Dashboard.

Default: `false`. | -| `merchant_support_email` | `String` | Optional | The email address to display on the Square Checkout confirmation page
and confirmation email that the buyer can use to contact the merchant.

If this value is not set, the confirmation page and email will display the
primary email address associated with the merchant's Square account.

Default: none; only exists if explicitly set. | -| `pre_populate_buyer_email` | `String` | Optional | If provided, the buyer's email is pre-populated on the checkout page
as an editable text field.

Default: none; only exists if explicitly set. | -| `pre_populate_shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `redirect_url` | `String` | Optional | The URL to redirect to after checkout is completed with `checkoutId`,
Square's `orderId`, `transactionId`, and `referenceId` appended as URL
parameters. For example, if the provided redirect_url is
`http://www.example.com/order-complete`, a successful transaction redirects
the customer to:

`http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx`

If you do not provide a redirect URL, Square Checkout will display an order
confirmation page on your behalf; however Square strongly recommends that
you provide a redirect URL so you can verify the transaction results and
finalize the order through your existing/normal confirmation workflow. | -| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | -| `created_at` | `String` | Optional | The time when the checkout was created, in RFC 3339 format. | -| `additional_recipients` | [`Array`](/doc/models/additional-recipient.md) | Optional | Additional recipients (other than the merchant) receiving a portion of this checkout.
For example, fees assessed on the purchase by a third party integration. | - -### Example (as JSON) - -```json -{ - "id": null, - "checkout_page_url": null, - "ask_for_shipping_address": null, - "merchant_support_email": null, - "pre_populate_buyer_email": null, - "pre_populate_shipping_address": null, - "redirect_url": null, - "order": null, - "created_at": null, - "additional_recipients": null -} -``` - +## Checkout + +Square Checkout lets merchants accept online payments for supported +payment types using a checkout workflow hosted on squareup.com. + +### Structure + +`Checkout` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | ID generated by Square Checkout when a new checkout is requested. | +| `checkout_page_url` | `String` | Optional | The URL that the buyer's browser should be redirected to after the
checkout is completed. | +| `ask_for_shipping_address` | `Boolean` | Optional | If `true`, Square Checkout will collect shipping information on your
behalf and store that information with the transaction information in your
Square Dashboard.

Default: `false`. | +| `merchant_support_email` | `String` | Optional | The email address to display on the Square Checkout confirmation page
and confirmation email that the buyer can use to contact the merchant.

If this value is not set, the confirmation page and email will display the
primary email address associated with the merchant's Square account.

Default: none; only exists if explicitly set. | +| `pre_populate_buyer_email` | `String` | Optional | If provided, the buyer's email is pre-populated on the checkout page
as an editable text field.

Default: none; only exists if explicitly set. | +| `pre_populate_shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `redirect_url` | `String` | Optional | The URL to redirect to after checkout is completed with `checkoutId`,
Square's `orderId`, `transactionId`, and `referenceId` appended as URL
parameters. For example, if the provided redirect_url is
`http://www.example.com/order-complete`, a successful transaction redirects
the customer to:

`http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx`

If you do not provide a redirect URL, Square Checkout will display an order
confirmation page on your behalf; however Square strongly recommends that
you provide a redirect URL so you can verify the transaction results and
finalize the order through your existing/normal confirmation workflow. | +| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | +| `created_at` | `String` | Optional | The time when the checkout was created, in RFC 3339 format. | +| `additional_recipients` | [`Array`](/doc/models/additional-recipient.md) | Optional | Additional recipients (other than the merchant) receiving a portion of this checkout.
For example, fees assessed on the purchase by a third party integration. | + +### Example (as JSON) + +```json +{ + "id": null, + "checkout_page_url": null, + "ask_for_shipping_address": null, + "merchant_support_email": null, + "pre_populate_buyer_email": null, + "pre_populate_shipping_address": null, + "redirect_url": null, + "order": null, + "created_at": null, + "additional_recipients": null +} +``` + diff --git a/doc/models/complete-payment-response.md b/doc/models/complete-payment-response.md index 829803f7..522b8ab6 100644 --- a/doc/models/complete-payment-response.md +++ b/doc/models/complete-payment-response.md @@ -1,60 +1,60 @@ -## Complete Payment Response - -Return value from a [CompletePayment](/doc/payments.md#completepayment) call. - -### Structure - -`CompletePaymentResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request | -| `payment` | [`Payment Hash`](/doc/models/payment.md) | Optional | Represents a payment processed by the Square API. | - -### Example (as JSON) - -```json -{ - "payment": { - "id": "EdMl5lwmBxd3ZvsvinkAT5LtvaB", - "created_at": "2019-07-10T13:39:55.317Z", - "updated_at": "2019-07-10T13:40:05.982Z", - "amount_money": { - "amount": 200, - "currency": "USD" - }, - "app_fee_money": { - "amount": 10, - "currency": "USD" - }, - "total_money": { - "amount": 200, - "currency": "USD" - }, - "status": "COMPLETED", - "source_type": "CARD", - "card_details": { - "status": "CAPTURED", - "card": { - "card_brand": "VISA", - "last_4": "2796", - "exp_month": 7, - "exp_year": 2026, - "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw" - }, - "entry_method": "ON_FILE", - "cvv_status": "CVV_ACCEPTED", - "avs_status": "AVS_ACCEPTED", - "auth_result_code": "MhIjEN" - }, - "location_id": "XK3DBG77NJBFX", - "order_id": "iJbzEHMhcwydeLbN3Apg5ZAjGi4F", - "reference_id": "123456", - "note": "Brief description", - "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8" - } -} -``` - +## Complete Payment Response + +Return value from a [CompletePayment](#endpoint-payments-completepayment) call. + +### Structure + +`CompletePaymentResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request | +| `payment` | [`Payment Hash`](/doc/models/payment.md) | Optional | Represents a payment processed by the Square API. | + +### Example (as JSON) + +```json +{ + "payment": { + "id": "EdMl5lwmBxd3ZvsvinkAT5LtvaB", + "created_at": "2019-07-10T13:39:55.317Z", + "updated_at": "2019-07-10T13:40:05.982Z", + "amount_money": { + "amount": 200, + "currency": "USD" + }, + "app_fee_money": { + "amount": 10, + "currency": "USD" + }, + "total_money": { + "amount": 200, + "currency": "USD" + }, + "status": "COMPLETED", + "source_type": "CARD", + "card_details": { + "status": "CAPTURED", + "card": { + "card_brand": "VISA", + "last_4": "2796", + "exp_month": 7, + "exp_year": 2026, + "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw" + }, + "entry_method": "ON_FILE", + "cvv_status": "CVV_ACCEPTED", + "avs_status": "AVS_ACCEPTED", + "auth_result_code": "MhIjEN" + }, + "location_id": "XK3DBG77NJBFX", + "order_id": "iJbzEHMhcwydeLbN3Apg5ZAjGi4F", + "reference_id": "123456", + "note": "Brief description", + "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8" + } +} +``` + diff --git a/doc/models/coordinates.md b/doc/models/coordinates.md index 8a9f0054..1e471d17 100644 --- a/doc/models/coordinates.md +++ b/doc/models/coordinates.md @@ -1,24 +1,24 @@ -## Coordinates - -Latitude and longitude coordinates. - -### Structure - -`Coordinates` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `latitude` | `Float` | Optional | The coordinate's latitude expressed in degrees. | -| `longitude` | `Float` | Optional | The coordinate's longitude expressed in degrees. | - -### Example (as JSON) - -```json -{ - "latitude": null, - "longitude": null -} -``` - +## Coordinates + +Latitude and longitude coordinates. + +### Structure + +`Coordinates` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `latitude` | `Float` | Optional | The coordinate's latitude expressed in degrees. | +| `longitude` | `Float` | Optional | The coordinate's longitude expressed in degrees. | + +### Example (as JSON) + +```json +{ + "latitude": null, + "longitude": null +} +``` + diff --git a/doc/models/country.md b/doc/models/country.md index 7674f1b8..9c7d64a1 100644 --- a/doc/models/country.md +++ b/doc/models/country.md @@ -1,264 +1,264 @@ -## Country - +## Country + Indicates the country associated with another entity, such as a business. -Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). - -### Enumeration - -`Country` - -### Fields - -| Name | Description | -| --- | --- | -| `ZZ` | - | -| `AD` | - | -| `AE` | - | -| `AF` | - | -| `AG` | - | -| `AI` | - | -| `AL` | - | -| `AM` | - | -| `AO` | - | -| `AQ` | - | -| `AR` | - | -| `AS` | - | -| `AT` | - | -| `AU` | - | -| `AW` | - | -| `AX` | - | -| `AZ` | - | -| `BA` | - | -| `BB` | - | -| `BD` | - | -| `BE` | - | -| `BF` | - | -| `BG` | - | -| `BH` | - | -| `BI` | - | -| `BJ` | - | -| `BL` | - | -| `BM` | - | -| `BN` | - | -| `BO` | - | -| `BQ` | - | -| `BR` | - | -| `BS` | - | -| `BT` | - | -| `BV` | - | -| `BW` | - | -| `BY` | - | -| `BZ` | - | -| `CA` | - | -| `CC` | - | -| `CD` | - | -| `CF` | - | -| `CG` | - | -| `CH` | - | -| `CI` | - | -| `CK` | - | -| `CL` | - | -| `CM` | - | -| `CN` | - | -| `CO` | - | -| `CR` | - | -| `CU` | - | -| `CV` | - | -| `CW` | - | -| `CX` | - | -| `CY` | - | -| `CZ` | - | -| `DE` | - | -| `DJ` | - | -| `DK` | - | -| `DM` | - | -| `DO` | - | -| `DZ` | - | -| `EC` | - | -| `EE` | - | -| `EG` | - | -| `EH` | - | -| `ER` | - | -| `ES` | - | -| `ET` | - | -| `FI` | - | -| `FJ` | - | -| `FK` | - | -| `FM` | - | -| `FO` | - | -| `FR` | - | -| `GA` | - | -| `GB` | - | -| `GD` | - | -| `GE` | - | -| `GF` | - | -| `GG` | - | -| `GH` | - | -| `GI` | - | -| `GL` | - | -| `GM` | - | -| `GN` | - | -| `GP` | - | -| `GQ` | - | -| `GR` | - | -| `GS` | - | -| `GT` | - | -| `GU` | - | -| `GW` | - | -| `GY` | - | -| `HK` | - | -| `HM` | - | -| `HN` | - | -| `HR` | - | -| `HT` | - | -| `HU` | - | -| `ID` | - | -| `IE` | - | -| `IL` | - | -| `IM` | - | -| `IN` | - | -| `IO` | - | -| `IQ` | - | -| `IR` | - | -| `IS` | - | -| `IT` | - | -| `JE` | - | -| `JM` | - | -| `JO` | - | -| `JP` | - | -| `KE` | - | -| `KG` | - | -| `KH` | - | -| `KI` | - | -| `KM` | - | -| `KN` | - | -| `KP` | - | -| `KR` | - | -| `KW` | - | -| `KY` | - | -| `KZ` | - | -| `LA` | - | -| `LB` | - | -| `LC` | - | -| `LI` | - | -| `LK` | - | -| `LR` | - | -| `LS` | - | -| `LT` | - | -| `LU` | - | -| `LV` | - | -| `LY` | - | -| `MA` | - | -| `MC` | - | -| `MD` | - | -| `ME` | - | -| `MF` | - | -| `MG` | - | -| `MH` | - | -| `MK` | - | -| `ML` | - | -| `MM` | - | -| `MN` | - | -| `MO` | - | -| `MP` | - | -| `MQ` | - | -| `MR` | - | -| `MS` | - | -| `MT` | - | -| `MU` | - | -| `MV` | - | -| `MW` | - | -| `MX` | - | -| `MY` | - | -| `MZ` | - | -| `NA` | - | -| `NC` | - | -| `NE` | - | -| `NF` | - | -| `NG` | - | -| `NI` | - | -| `NL` | - | -| `NO` | - | -| `NP` | - | -| `NR` | - | -| `NU` | - | -| `NZ` | - | -| `OM` | - | -| `PA` | - | -| `PE` | - | -| `PF` | - | -| `PG` | - | -| `PH` | - | -| `PK` | - | -| `PL` | - | -| `PM` | - | -| `PN` | - | -| `PR` | - | -| `PS` | - | -| `PT` | - | -| `PW` | - | -| `PY` | - | -| `QA` | - | -| `RE` | - | -| `RO` | - | -| `RS` | - | -| `RU` | - | -| `RW` | - | -| `SA` | - | -| `SB` | - | -| `SC` | - | -| `SD` | - | -| `SE` | - | -| `SG` | - | -| `SH` | - | -| `SI` | - | -| `SJ` | - | -| `SK` | - | -| `SL` | - | -| `SM` | - | -| `SN` | - | -| `SO` | - | -| `SR` | - | -| `SS` | - | -| `ST` | - | -| `SV` | - | -| `SX` | - | -| `SY` | - | -| `SZ` | - | -| `TC` | - | -| `TD` | - | -| `TF` | - | -| `TG` | - | -| `TH` | - | -| `TJ` | - | -| `TK` | - | -| `TL` | - | -| `TM` | - | -| `TN` | - | -| `TO` | - | -| `TR` | - | -| `TT` | - | -| `TV` | - | -| `TW` | - | -| `TZ` | - | -| `UA` | - | -| `UG` | - | -| `UM` | - | -| `US` | - | -| `UY` | - | -| `UZ` | - | -| `VA` | - | -| `VC` | - | -| `VE` | - | -| `VG` | - | -| `VI` | - | -| `VN` | - | -| `VU` | - | -| `WF` | - | -| `WS` | - | -| `YE` | - | -| `YT` | - | -| `ZA` | - | -| `ZM` | - | -| `ZW` | - | - +Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). + +### Enumeration + +`Country` + +### Fields + +| Name | Description | +| --- | --- | +| `ZZ` | - | +| `AD` | - | +| `AE` | - | +| `AF` | - | +| `AG` | - | +| `AI` | - | +| `AL` | - | +| `AM` | - | +| `AO` | - | +| `AQ` | - | +| `AR` | - | +| `AS` | - | +| `AT` | - | +| `AU` | - | +| `AW` | - | +| `AX` | - | +| `AZ` | - | +| `BA` | - | +| `BB` | - | +| `BD` | - | +| `BE` | - | +| `BF` | - | +| `BG` | - | +| `BH` | - | +| `BI` | - | +| `BJ` | - | +| `BL` | - | +| `BM` | - | +| `BN` | - | +| `BO` | - | +| `BQ` | - | +| `BR` | - | +| `BS` | - | +| `BT` | - | +| `BV` | - | +| `BW` | - | +| `BY` | - | +| `BZ` | - | +| `CA` | - | +| `CC` | - | +| `CD` | - | +| `CF` | - | +| `CG` | - | +| `CH` | - | +| `CI` | - | +| `CK` | - | +| `CL` | - | +| `CM` | - | +| `CN` | - | +| `CO` | - | +| `CR` | - | +| `CU` | - | +| `CV` | - | +| `CW` | - | +| `CX` | - | +| `CY` | - | +| `CZ` | - | +| `DE` | - | +| `DJ` | - | +| `DK` | - | +| `DM` | - | +| `DO` | - | +| `DZ` | - | +| `EC` | - | +| `EE` | - | +| `EG` | - | +| `EH` | - | +| `ER` | - | +| `ES` | - | +| `ET` | - | +| `FI` | - | +| `FJ` | - | +| `FK` | - | +| `FM` | - | +| `FO` | - | +| `FR` | - | +| `GA` | - | +| `GB` | - | +| `GD` | - | +| `GE` | - | +| `GF` | - | +| `GG` | - | +| `GH` | - | +| `GI` | - | +| `GL` | - | +| `GM` | - | +| `GN` | - | +| `GP` | - | +| `GQ` | - | +| `GR` | - | +| `GS` | - | +| `GT` | - | +| `GU` | - | +| `GW` | - | +| `GY` | - | +| `HK` | - | +| `HM` | - | +| `HN` | - | +| `HR` | - | +| `HT` | - | +| `HU` | - | +| `ID` | - | +| `IE` | - | +| `IL` | - | +| `IM` | - | +| `IN` | - | +| `IO` | - | +| `IQ` | - | +| `IR` | - | +| `IS` | - | +| `IT` | - | +| `JE` | - | +| `JM` | - | +| `JO` | - | +| `JP` | - | +| `KE` | - | +| `KG` | - | +| `KH` | - | +| `KI` | - | +| `KM` | - | +| `KN` | - | +| `KP` | - | +| `KR` | - | +| `KW` | - | +| `KY` | - | +| `KZ` | - | +| `LA` | - | +| `LB` | - | +| `LC` | - | +| `LI` | - | +| `LK` | - | +| `LR` | - | +| `LS` | - | +| `LT` | - | +| `LU` | - | +| `LV` | - | +| `LY` | - | +| `MA` | - | +| `MC` | - | +| `MD` | - | +| `ME` | - | +| `MF` | - | +| `MG` | - | +| `MH` | - | +| `MK` | - | +| `ML` | - | +| `MM` | - | +| `MN` | - | +| `MO` | - | +| `MP` | - | +| `MQ` | - | +| `MR` | - | +| `MS` | - | +| `MT` | - | +| `MU` | - | +| `MV` | - | +| `MW` | - | +| `MX` | - | +| `MY` | - | +| `MZ` | - | +| `NA` | - | +| `NC` | - | +| `NE` | - | +| `NF` | - | +| `NG` | - | +| `NI` | - | +| `NL` | - | +| `NO` | - | +| `NP` | - | +| `NR` | - | +| `NU` | - | +| `NZ` | - | +| `OM` | - | +| `PA` | - | +| `PE` | - | +| `PF` | - | +| `PG` | - | +| `PH` | - | +| `PK` | - | +| `PL` | - | +| `PM` | - | +| `PN` | - | +| `PR` | - | +| `PS` | - | +| `PT` | - | +| `PW` | - | +| `PY` | - | +| `QA` | - | +| `RE` | - | +| `RO` | - | +| `RS` | - | +| `RU` | - | +| `RW` | - | +| `SA` | - | +| `SB` | - | +| `SC` | - | +| `SD` | - | +| `SE` | - | +| `SG` | - | +| `SH` | - | +| `SI` | - | +| `SJ` | - | +| `SK` | - | +| `SL` | - | +| `SM` | - | +| `SN` | - | +| `SO` | - | +| `SR` | - | +| `SS` | - | +| `ST` | - | +| `SV` | - | +| `SX` | - | +| `SY` | - | +| `SZ` | - | +| `TC` | - | +| `TD` | - | +| `TF` | - | +| `TG` | - | +| `TH` | - | +| `TJ` | - | +| `TK` | - | +| `TL` | - | +| `TM` | - | +| `TN` | - | +| `TO` | - | +| `TR` | - | +| `TT` | - | +| `TV` | - | +| `TW` | - | +| `TZ` | - | +| `UA` | - | +| `UG` | - | +| `UM` | - | +| `US` | - | +| `UY` | - | +| `UZ` | - | +| `VA` | - | +| `VC` | - | +| `VE` | - | +| `VG` | - | +| `VI` | - | +| `VN` | - | +| `VU` | - | +| `WF` | - | +| `WS` | - | +| `YE` | - | +| `YT` | - | +| `ZA` | - | +| `ZM` | - | +| `ZW` | - | + diff --git a/doc/models/create-break-type-request.md b/doc/models/create-break-type-request.md index 04c31c68..c3c2fdd5 100644 --- a/doc/models/create-break-type-request.md +++ b/doc/models/create-break-type-request.md @@ -1,29 +1,29 @@ -## Create Break Type Request - -A request to create a new `BreakType` - -### Structure - -`CreateBreakTypeRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `idempotency_key` | `String` | Optional | Unique string value to insure idempotency of the operation | -| `break_type` | [`Break Type Hash`](/doc/models/break-type.md) | | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. | - -### Example (as JSON) - -```json -{ - "idempotency_key": "PAD3NG5KSN2GL", - "break_type": { - "location_id": "CGJN03P1D08GF", - "break_name": "Lunch Break", - "expected_duration": "PT30M", - "is_paid": true - } -} -``` - +## Create Break Type Request + +A request to create a new `BreakType` + +### Structure + +`CreateBreakTypeRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `String` | Optional | Unique string value to insure idempotency of the operation | +| `break_type` | [`Break Type Hash`](/doc/models/break-type.md) | | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. | + +### Example (as JSON) + +```json +{ + "idempotency_key": "PAD3NG5KSN2GL", + "break_type": { + "location_id": "CGJN03P1D08GF", + "break_name": "Lunch Break", + "expected_duration": "PT30M", + "is_paid": true + } +} +``` + diff --git a/doc/models/create-break-type-response.md b/doc/models/create-break-type-response.md index daf8e4ac..d1d0e93f 100644 --- a/doc/models/create-break-type-response.md +++ b/doc/models/create-break-type-response.md @@ -1,34 +1,34 @@ -## Create Break Type Response - -The response to the request to create a `BreakType`. Contains -the created `BreakType` object. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`CreateBreakTypeResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `break_type` | [`Break Type Hash`](/doc/models/break-type.md) | Optional | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "break_type": { - "id": "49SSVDJG76WF3", - "location_id": "CGJN03P1D08GF", - "break_name": "Lunch Break", - "expected_duration": "PT30M", - "is_paid": true, - "version": 1, - "created_at": "2019-02-26T22:42:54Z", - "updated_at": "2019-02-26T22:42:54Z" - } -} -``` - +## Create Break Type Response + +The response to the request to create a `BreakType`. Contains +the created `BreakType` object. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`CreateBreakTypeResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `break_type` | [`Break Type Hash`](/doc/models/break-type.md) | Optional | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "break_type": { + "id": "49SSVDJG76WF3", + "location_id": "CGJN03P1D08GF", + "break_name": "Lunch Break", + "expected_duration": "PT30M", + "is_paid": true, + "version": 1, + "created_at": "2019-02-26T22:42:54Z", + "updated_at": "2019-02-26T22:42:54Z" + } +} +``` + diff --git a/doc/models/create-checkout-request.md b/doc/models/create-checkout-request.md index 851c2a6c..6c963dd8 100644 --- a/doc/models/create-checkout-request.md +++ b/doc/models/create-checkout-request.md @@ -1,131 +1,131 @@ -## Create Checkout Request - -Defines the parameters that can be included in the body of -a request to the CreateCheckout endpoint. - -### Structure - -`CreateCheckoutRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `idempotency_key` | `String` | | A unique string that identifies this checkout among others
you've created. It can be any valid string but must be unique for every
order sent to Square Checkout for a given location ID.

The idempotency key is used to avoid processing the same order more than
once. If you're unsure whether a particular checkout was created
successfully, you can reattempt it with the same idempotency key and all the
same other parameters without worrying about creating duplicates.

We recommend using a random number/string generator native to the language
you are working in to generate strings for your idempotency keys.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | -| `order` | [`Create Order Request Hash`](/doc/models/create-order-request.md) | | - | -| `ask_for_shipping_address` | `Boolean` | Optional | If `true`, Square Checkout will collect shipping information on your
behalf and store that information with the transaction information in your
Square Dashboard.

Default: `false`. | -| `merchant_support_email` | `String` | Optional | The email address to display on the Square Checkout confirmation page
and confirmation email that the buyer can use to contact the merchant.

If this value is not set, the confirmation page and email will display the
primary email address associated with the merchant's Square account.

Default: none; only exists if explicitly set. | -| `pre_populate_buyer_email` | `String` | Optional | If provided, the buyer's email is pre-populated on the checkout page
as an editable text field.

Default: none; only exists if explicitly set. | -| `pre_populate_shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `redirect_url` | `String` | Optional | The URL to redirect to after checkout is completed with `checkoutId`,
Square's `orderId`, `transactionId`, and `referenceId` appended as URL
parameters. For example, if the provided redirect_url is
`http://www.example.com/order-complete`, a successful transaction redirects
the customer to:

`http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx`

If you do not provide a redirect URL, Square Checkout will display an order
confirmation page on your behalf; however Square strongly recommends that
you provide a redirect URL so you can verify the transaction results and
finalize the order through your existing/normal confirmation workflow.

Default: none; only exists if explicitly set. | -| `additional_recipients` | [`Array`](/doc/models/charge-request-additional-recipient.md) | Optional | The basic primitive of multi-party transaction. The value is optional.
The transaction facilitated by you can be split from here.

If you provide this value, the `amount_money` value in your additional_recipients
must not be more than 90% of the `total_money` calculated by Square for your order.
The `location_id` must be the valid location of the app owner merchant.

This field requires `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission.

This field is currently not supported in sandbox. | -| `note` | `String` | Optional | An optional note to associate with the checkout object.

This value cannot exceed 60 characters. | - -### Example (as JSON) - -```json -{ - "idempotency_key": "86ae1696-b1e3-4328-af6d-f1e04d947ad6", - "order": { - "reference_id": "reference_id", - "line_items": [ - { - "name": "Printed T Shirt", - "quantity": "2", - "base_price_money": { - "amount": 1500, - "currency": "USD" - }, - "discounts": [ - { - "name": "7% off previous season item", - "percentage": "7" - }, - { - "name": "$3 off Customer Discount", - "amount_money": { - "amount": 300, - "currency": "USD" - } - } - ] - }, - { - "name": "Slim Jeans", - "quantity": "1", - "base_price_money": { - "amount": 2500, - "currency": "USD" - } - }, - { - "name": "Woven Sweater", - "quantity": "3", - "base_price_money": { - "amount": 3500, - "currency": "USD" - }, - "discounts": [ - { - "name": "$11 off Customer Discount", - "amount_money": { - "amount": 1100, - "currency": "USD" - } - } - ], - "taxes": [ - { - "name": "Fair Trade Tax", - "percentage": "5" - } - ] - } - ], - "discounts": [ - { - "name": "Father's day 12% OFF", - "percentage": "12" - }, - { - "name": "Global Sales $55 OFF", - "amount_money": { - "amount": 5500, - "currency": "USD" - } - } - ], - "taxes": [ - { - "name": "Sales Tax", - "percentage": "8.5" - } - ] - }, - "additional_recipients": [ - { - "location_id": "057P5VYJ4A5X1", - "description": "Application fees", - "amount_money": { - "amount": 60, - "currency": "USD" - } - } - ], - "ask_for_shipping_address": true, - "merchant_support_email": "merchant+support@website.com", - "pre_populate_buyer_email": "example@email.com", - "pre_populate_shipping_address": { - "address_line_1": "1455 Market St.", - "address_line_2": "Suite 600", - "locality": "San Francisco", - "administrative_district_level_1": "CA", - "postal_code": "94103", - "country": "US", - "first_name": "Jane", - "last_name": "Doe" - }, - "redirect_url": "https://merchant.website.com/order-confirm" -} -``` - +## Create Checkout Request + +Defines the parameters that can be included in the body of +a request to the CreateCheckout endpoint. + +### Structure + +`CreateCheckoutRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `String` | | A unique string that identifies this checkout among others
you've created. It can be any valid string but must be unique for every
order sent to Square Checkout for a given location ID.

The idempotency key is used to avoid processing the same order more than
once. If you're unsure whether a particular checkout was created
successfully, you can reattempt it with the same idempotency key and all the
same other parameters without worrying about creating duplicates.

We recommend using a random number/string generator native to the language
you are working in to generate strings for your idempotency keys.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | +| `order` | [`Create Order Request Hash`](/doc/models/create-order-request.md) | | - | +| `ask_for_shipping_address` | `Boolean` | Optional | If `true`, Square Checkout will collect shipping information on your
behalf and store that information with the transaction information in your
Square Dashboard.

Default: `false`. | +| `merchant_support_email` | `String` | Optional | The email address to display on the Square Checkout confirmation page
and confirmation email that the buyer can use to contact the merchant.

If this value is not set, the confirmation page and email will display the
primary email address associated with the merchant's Square account.

Default: none; only exists if explicitly set. | +| `pre_populate_buyer_email` | `String` | Optional | If provided, the buyer's email is pre-populated on the checkout page
as an editable text field.

Default: none; only exists if explicitly set. | +| `pre_populate_shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `redirect_url` | `String` | Optional | The URL to redirect to after checkout is completed with `checkoutId`,
Square's `orderId`, `transactionId`, and `referenceId` appended as URL
parameters. For example, if the provided redirect_url is
`http://www.example.com/order-complete`, a successful transaction redirects
the customer to:

`http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx`

If you do not provide a redirect URL, Square Checkout will display an order
confirmation page on your behalf; however Square strongly recommends that
you provide a redirect URL so you can verify the transaction results and
finalize the order through your existing/normal confirmation workflow.

Default: none; only exists if explicitly set. | +| `additional_recipients` | [`Array`](/doc/models/charge-request-additional-recipient.md) | Optional | The basic primitive of multi-party transaction. The value is optional.
The transaction facilitated by you can be split from here.

If you provide this value, the `amount_money` value in your additional_recipients
must not be more than 90% of the `total_money` calculated by Square for your order.
The `location_id` must be the valid location of the app owner merchant.

This field requires `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission.

This field is currently not supported in sandbox. | +| `note` | `String` | Optional | An optional note to associate with the checkout object.

This value cannot exceed 60 characters. | + +### Example (as JSON) + +```json +{ + "idempotency_key": "86ae1696-b1e3-4328-af6d-f1e04d947ad6", + "order": { + "reference_id": "reference_id", + "line_items": [ + { + "name": "Printed T Shirt", + "quantity": "2", + "base_price_money": { + "amount": 1500, + "currency": "USD" + }, + "discounts": [ + { + "name": "7% off previous season item", + "percentage": "7" + }, + { + "name": "$3 off Customer Discount", + "amount_money": { + "amount": 300, + "currency": "USD" + } + } + ] + }, + { + "name": "Slim Jeans", + "quantity": "1", + "base_price_money": { + "amount": 2500, + "currency": "USD" + } + }, + { + "name": "Woven Sweater", + "quantity": "3", + "base_price_money": { + "amount": 3500, + "currency": "USD" + }, + "discounts": [ + { + "name": "$11 off Customer Discount", + "amount_money": { + "amount": 1100, + "currency": "USD" + } + } + ], + "taxes": [ + { + "name": "Fair Trade Tax", + "percentage": "5" + } + ] + } + ], + "discounts": [ + { + "name": "Father's day 12% OFF", + "percentage": "12" + }, + { + "name": "Global Sales $55 OFF", + "amount_money": { + "amount": 5500, + "currency": "USD" + } + } + ], + "taxes": [ + { + "name": "Sales Tax", + "percentage": "8.5" + } + ] + }, + "additional_recipients": [ + { + "location_id": "057P5VYJ4A5X1", + "description": "Application fees", + "amount_money": { + "amount": 60, + "currency": "USD" + } + } + ], + "ask_for_shipping_address": true, + "merchant_support_email": "merchant+support@website.com", + "pre_populate_buyer_email": "example@email.com", + "pre_populate_shipping_address": { + "address_line_1": "1455 Market St.", + "address_line_2": "Suite 600", + "locality": "San Francisco", + "administrative_district_level_1": "CA", + "postal_code": "94103", + "country": "US", + "first_name": "Jane", + "last_name": "Doe" + }, + "redirect_url": "https://merchant.website.com/order-confirm" +} +``` + diff --git a/doc/models/create-checkout-response.md b/doc/models/create-checkout-response.md index 4b247712..3cfb119a 100644 --- a/doc/models/create-checkout-response.md +++ b/doc/models/create-checkout-response.md @@ -1,283 +1,283 @@ -## Create Checkout Response - -Defines the fields that are included in the response body of -a request to the CreateCheckout endpoint. - -### Structure - -`CreateCheckoutResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `checkout` | [`Checkout Hash`](/doc/models/checkout.md) | Optional | Square Checkout lets merchants accept online payments for supported
payment types using a checkout workflow hosted on squareup.com. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "checkout": { - "id": "CAISEHGimXh-C3RIT4og1a6u1qw", - "checkout_page_url": "https://connect.squareup.com/v2/checkout?c=CAISEHGimXh-C3RIT4og1a6u1qw&l=CYTKRM7R7JMV8", - "ask_for_shipping_address": true, - "merchant_support_email": "merchant+support@website.com", - "pre_populate_buyer_email": "example@email.com", - "pre_populate_shipping_address": { - "address_line_1": "1455 Market St.", - "address_line_2": "Suite 600", - "locality": "San Francisco", - "administrative_district_level_1": "CA", - "postal_code": "94103", - "country": "US", - "first_name": "Jane", - "last_name": "Doe" - }, - "redirect_url": "https://merchant.website.com/order-confirm", - "order": { - "location_id": "CYTKRM7R7JMV8", - "reference_id": "reference_id", - "line_items": [ - { - "name": "Printed T Shirt", - "quantity": "2", - "taxes": [ - { - "name": "Sales Tax", - "type": "ADDITIVE", - "percentage": "8.5", - "applied_money": { - "amount": 103, - "currency": "USD" - } - } - ], - "discounts": [ - { - "name": "7% off previous season item", - "type": "FIXED_PERCENTAGE", - "percentage": "7", - "applied_money": { - "amount": 210, - "currency": "USD" - }, - "scope": "LINE_ITEM" - }, - { - "name": "Father's day 12% OFF", - "type": "FIXED_PERCENTAGE", - "percentage": "12", - "applied_money": { - "amount": 335, - "currency": "USD" - }, - "scope": "ORDER" - }, - { - "name": "$3 off Customer Discount", - "type": "FIXED_AMOUNT", - "amount_money": { - "amount": 300, - "currency": "USD" - }, - "applied_money": { - "amount": 300, - "currency": "USD" - }, - "scope": "LINE_ITEM" - }, - { - "name": "Global Sales $55 OFF", - "type": "FIXED_AMOUNT", - "amount_money": { - "amount": 5500, - "currency": "USD" - }, - "applied_money": { - "amount": 949, - "currency": "USD" - }, - "scope": "ORDER" - } - ], - "base_price_money": { - "amount": 1500, - "currency": "USD" - }, - "total_tax_money": { - "amount": 103, - "currency": "USD" - }, - "total_discount_money": { - "amount": 1794, - "currency": "USD" - }, - "total_money": { - "amount": 1309, - "currency": "USD" - } - }, - { - "name": "Slim Jeans", - "quantity": "1", - "taxes": [ - { - "name": "Sales Tax", - "type": "ADDITIVE", - "percentage": "8.5", - "applied_money": { - "amount": 105, - "currency": "USD" - } - } - ], - "discounts": [ - { - "name": "Father's day 12% OFF", - "type": "FIXED_PERCENTAGE", - "percentage": "12", - "applied_money": { - "amount": 300, - "currency": "USD" - }, - "scope": "ORDER" - }, - { - "name": "Global Sales $55 OFF", - "type": "FIXED_AMOUNT", - "amount_money": { - "amount": 5500, - "currency": "USD" - }, - "applied_money": { - "amount": 968, - "currency": "USD" - }, - "scope": "ORDER" - } - ], - "base_price_money": { - "amount": 2500, - "currency": "USD" - }, - "total_tax_money": { - "amount": 105, - "currency": "USD" - }, - "total_discount_money": { - "amount": 1268, - "currency": "USD" - }, - "total_money": { - "amount": 1337, - "currency": "USD" - } - }, - { - "name": "Wooven Sweater", - "quantity": "3", - "taxes": [ - { - "name": "Fair Trade Tax", - "type": "ADDITIVE", - "percentage": "5", - "applied_money": { - "amount": 228, - "currency": "USD" - } - }, - { - "name": "Sales Tax", - "type": "ADDITIVE", - "percentage": "8.5", - "applied_money": { - "amount": 387, - "currency": "USD" - } - } - ], - "discounts": [ - { - "name": "Father's day 12% OFF", - "type": "FIXED_PERCENTAGE", - "percentage": "12", - "applied_money": { - "amount": 1260, - "currency": "USD" - }, - "scope": "ORDER" - }, - { - "name": "$11 off Customer Discount", - "type": "FIXED_AMOUNT", - "amount_money": { - "amount": 1100, - "currency": "USD" - }, - "applied_money": { - "amount": 1100, - "currency": "USD" - }, - "scope": "LINE_ITEM" - }, - { - "name": "Global Sales $55 OFF", - "type": "FIXED_AMOUNT", - "amount_money": { - "amount": 5500, - "currency": "USD" - }, - "applied_money": { - "amount": 3583, - "currency": "USD" - }, - "scope": "ORDER" - } - ], - "base_price_money": { - "amount": 3500, - "currency": "USD" - }, - "total_tax_money": { - "amount": 615, - "currency": "USD" - }, - "total_discount_money": { - "amount": 5943, - "currency": "USD" - }, - "total_money": { - "amount": 5172, - "currency": "USD" - } - } - ], - "total_money": { - "amount": 7818, - "currency": "USD" - }, - "total_tax_money": { - "amount": 823, - "currency": "USD" - }, - "total_discount_money": { - "amount": 9005, - "currency": "USD" - } - }, - "created_at": "2017-06-16T22:25:35Z", - "additional_recipients": [ - { - "location_id": "057P5VYJ4A5X1", - "description": "Application fees", - "amount_money": { - "amount": 60, - "currency": "USD" - } - } - ] - } -} -``` - +## Create Checkout Response + +Defines the fields that are included in the response body of +a request to the CreateCheckout endpoint. + +### Structure + +`CreateCheckoutResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `checkout` | [`Checkout Hash`](/doc/models/checkout.md) | Optional | Square Checkout lets merchants accept online payments for supported
payment types using a checkout workflow hosted on squareup.com. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "checkout": { + "id": "CAISEHGimXh-C3RIT4og1a6u1qw", + "checkout_page_url": "https://connect.squareup.com/v2/checkout?c=CAISEHGimXh-C3RIT4og1a6u1qw&l=CYTKRM7R7JMV8", + "ask_for_shipping_address": true, + "merchant_support_email": "merchant+support@website.com", + "pre_populate_buyer_email": "example@email.com", + "pre_populate_shipping_address": { + "address_line_1": "1455 Market St.", + "address_line_2": "Suite 600", + "locality": "San Francisco", + "administrative_district_level_1": "CA", + "postal_code": "94103", + "country": "US", + "first_name": "Jane", + "last_name": "Doe" + }, + "redirect_url": "https://merchant.website.com/order-confirm", + "order": { + "location_id": "CYTKRM7R7JMV8", + "reference_id": "reference_id", + "line_items": [ + { + "name": "Printed T Shirt", + "quantity": "2", + "taxes": [ + { + "name": "Sales Tax", + "type": "ADDITIVE", + "percentage": "8.5", + "applied_money": { + "amount": 103, + "currency": "USD" + } + } + ], + "discounts": [ + { + "name": "7% off previous season item", + "type": "FIXED_PERCENTAGE", + "percentage": "7", + "applied_money": { + "amount": 210, + "currency": "USD" + }, + "scope": "LINE_ITEM" + }, + { + "name": "Father's day 12% OFF", + "type": "FIXED_PERCENTAGE", + "percentage": "12", + "applied_money": { + "amount": 335, + "currency": "USD" + }, + "scope": "ORDER" + }, + { + "name": "$3 off Customer Discount", + "type": "FIXED_AMOUNT", + "amount_money": { + "amount": 300, + "currency": "USD" + }, + "applied_money": { + "amount": 300, + "currency": "USD" + }, + "scope": "LINE_ITEM" + }, + { + "name": "Global Sales $55 OFF", + "type": "FIXED_AMOUNT", + "amount_money": { + "amount": 5500, + "currency": "USD" + }, + "applied_money": { + "amount": 949, + "currency": "USD" + }, + "scope": "ORDER" + } + ], + "base_price_money": { + "amount": 1500, + "currency": "USD" + }, + "total_tax_money": { + "amount": 103, + "currency": "USD" + }, + "total_discount_money": { + "amount": 1794, + "currency": "USD" + }, + "total_money": { + "amount": 1309, + "currency": "USD" + } + }, + { + "name": "Slim Jeans", + "quantity": "1", + "taxes": [ + { + "name": "Sales Tax", + "type": "ADDITIVE", + "percentage": "8.5", + "applied_money": { + "amount": 105, + "currency": "USD" + } + } + ], + "discounts": [ + { + "name": "Father's day 12% OFF", + "type": "FIXED_PERCENTAGE", + "percentage": "12", + "applied_money": { + "amount": 300, + "currency": "USD" + }, + "scope": "ORDER" + }, + { + "name": "Global Sales $55 OFF", + "type": "FIXED_AMOUNT", + "amount_money": { + "amount": 5500, + "currency": "USD" + }, + "applied_money": { + "amount": 968, + "currency": "USD" + }, + "scope": "ORDER" + } + ], + "base_price_money": { + "amount": 2500, + "currency": "USD" + }, + "total_tax_money": { + "amount": 105, + "currency": "USD" + }, + "total_discount_money": { + "amount": 1268, + "currency": "USD" + }, + "total_money": { + "amount": 1337, + "currency": "USD" + } + }, + { + "name": "Wooven Sweater", + "quantity": "3", + "taxes": [ + { + "name": "Fair Trade Tax", + "type": "ADDITIVE", + "percentage": "5", + "applied_money": { + "amount": 228, + "currency": "USD" + } + }, + { + "name": "Sales Tax", + "type": "ADDITIVE", + "percentage": "8.5", + "applied_money": { + "amount": 387, + "currency": "USD" + } + } + ], + "discounts": [ + { + "name": "Father's day 12% OFF", + "type": "FIXED_PERCENTAGE", + "percentage": "12", + "applied_money": { + "amount": 1260, + "currency": "USD" + }, + "scope": "ORDER" + }, + { + "name": "$11 off Customer Discount", + "type": "FIXED_AMOUNT", + "amount_money": { + "amount": 1100, + "currency": "USD" + }, + "applied_money": { + "amount": 1100, + "currency": "USD" + }, + "scope": "LINE_ITEM" + }, + { + "name": "Global Sales $55 OFF", + "type": "FIXED_AMOUNT", + "amount_money": { + "amount": 5500, + "currency": "USD" + }, + "applied_money": { + "amount": 3583, + "currency": "USD" + }, + "scope": "ORDER" + } + ], + "base_price_money": { + "amount": 3500, + "currency": "USD" + }, + "total_tax_money": { + "amount": 615, + "currency": "USD" + }, + "total_discount_money": { + "amount": 5943, + "currency": "USD" + }, + "total_money": { + "amount": 5172, + "currency": "USD" + } + } + ], + "total_money": { + "amount": 7818, + "currency": "USD" + }, + "total_tax_money": { + "amount": 823, + "currency": "USD" + }, + "total_discount_money": { + "amount": 9005, + "currency": "USD" + } + }, + "created_at": "2017-06-16T22:25:35Z", + "additional_recipients": [ + { + "location_id": "057P5VYJ4A5X1", + "description": "Application fees", + "amount_money": { + "amount": 60, + "currency": "USD" + } + } + ] + } +} +``` + diff --git a/doc/models/create-customer-card-request.md b/doc/models/create-customer-card-request.md index 8ff4435d..c80d3372 100644 --- a/doc/models/create-customer-card-request.md +++ b/doc/models/create-customer-card-request.md @@ -1,35 +1,35 @@ -## Create Customer Card Request - -Defines the fields that are included in the request body of a request -to the CreateCustomerCard endpoint. - -### Structure - -`CreateCustomerCardRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `card_nonce` | `String` | | A card nonce representing the credit card to link to the customer.

Card nonces are generated by the `SqPaymentForm` that buyers enter
their card information into. See
[Embedding the payment form](https://developer.squareup.com/docs/payment-form/payment-form-walkthrough) for
more information.

__Note:__ Card nonces generated by digital wallets (e.g., Apple Pay)
cannot be used to create a customer card. | -| `billing_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `cardholder_name` | `String` | Optional | The full name printed on the credit card. | -| `verification_token` | `String` | Optional | An identifying token generated by `SqPaymentForm.verifyBuyer()`.
Verification tokens encapsulate customer device information and 3-D Secure
challenge results to indicate that Square has verified the buyer identity. | - -### Example (as JSON) - -```json -{ - "card_nonce": "YOUR_CARD_NONCE", - "billing_address": { - "address_line_1": "500 Electric Ave", - "address_line_2": "Suite 600", - "locality": "New York", - "administrative_district_level_1": "NY", - "postal_code": "10003", - "country": "US" - }, - "cardholder_name": "Amelia Earhart" -} -``` - +## Create Customer Card Request + +Defines the fields that are included in the request body of a request +to the CreateCustomerCard endpoint. + +### Structure + +`CreateCustomerCardRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `card_nonce` | `String` | | A card nonce representing the credit card to link to the customer.

Card nonces are generated by the `SqPaymentForm` that buyers enter
their card information into. See
[Embedding the payment form](https://developer.squareup.com/docs/payment-form/payment-form-walkthrough) for
more information.

__Note:__ Card nonces generated by digital wallets (e.g., Apple Pay)
cannot be used to create a customer card. | +| `billing_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `cardholder_name` | `String` | Optional | The full name printed on the credit card. | +| `verification_token` | `String` | Optional | An identifying token generated by `SqPaymentForm.verifyBuyer()`.
Verification tokens encapsulate customer device information and 3-D Secure
challenge results to indicate that Square has verified the buyer identity. | + +### Example (as JSON) + +```json +{ + "card_nonce": "YOUR_CARD_NONCE", + "billing_address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "locality": "New York", + "administrative_district_level_1": "NY", + "postal_code": "10003", + "country": "US" + }, + "cardholder_name": "Amelia Earhart" +} +``` + diff --git a/doc/models/create-customer-card-response.md b/doc/models/create-customer-card-response.md index 91df7dcf..e30165a6 100644 --- a/doc/models/create-customer-card-response.md +++ b/doc/models/create-customer-card-response.md @@ -1,41 +1,41 @@ -## Create Customer Card Response - -Defines the fields that are included in the response body of -a request to the CreateCustomerCard endpoint. - -One of `errors` or `card` is present in a given response (never both). - -### Structure - -`CreateCustomerCardResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `card` | [`Card Hash`](/doc/models/card.md) | Optional | Represents the payment details of a card to be used for payments. These
details are determined by the `card_nonce` generated by `SqPaymentForm`. | - -### Example (as JSON) - -```json -{ - "card": { - "id": "icard-card_id", - "card_brand": "VISA", - "last_4": "1111", - "exp_month": 11, - "exp_year": 2018, - "cardholder_name": "Amelia Earhart", - "billing_address": { - "address_line_1": "500 Electric Ave", - "address_line_2": "Suite 600", - "locality": "New York", - "administrative_district_level_1": "NY", - "postal_code": "10003", - "country": "US" - } - } -} -``` - +## Create Customer Card Response + +Defines the fields that are included in the response body of +a request to the CreateCustomerCard endpoint. + +One of `errors` or `card` is present in a given response (never both). + +### Structure + +`CreateCustomerCardResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `card` | [`Card Hash`](/doc/models/card.md) | Optional | Represents the payment details of a card to be used for payments. These
details are determined by the `card_nonce` generated by `SqPaymentForm`. | + +### Example (as JSON) + +```json +{ + "card": { + "id": "icard-card_id", + "card_brand": "VISA", + "last_4": "1111", + "exp_month": 11, + "exp_year": 2018, + "cardholder_name": "Amelia Earhart", + "billing_address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "locality": "New York", + "administrative_district_level_1": "NY", + "postal_code": "10003", + "country": "US" + } + } +} +``` + diff --git a/doc/models/create-customer-request.md b/doc/models/create-customer-request.md index ff51ba67..10928389 100644 --- a/doc/models/create-customer-request.md +++ b/doc/models/create-customer-request.md @@ -1,46 +1,46 @@ -## Create Customer Request - -Defines the body parameters that can be provided in a request to the -CreateCustomer endpoint. - -### Structure - -`CreateCustomerRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `idempotency_key` | `String` | Optional | The idempotency key for the request. See the [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency)
guide for more information. | -| `given_name` | `String` | Optional | The customer's given (i.e., first) name. | -| `family_name` | `String` | Optional | The customer's family (i.e., last) name. | -| `company_name` | `String` | Optional | The name of the customer's company. | -| `nickname` | `String` | Optional | A nickname for the customer. | -| `email_address` | `String` | Optional | The customer's email address. | -| `address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `phone_number` | `String` | Optional | The customer's phone number. | -| `reference_id` | `String` | Optional | An optional second ID you can set to associate the customer with an
entity in another system. | -| `note` | `String` | Optional | An optional note to associate with the customer. | -| `birthday` | `String` | Optional | The customer birthday in RFC-3339 format. Year is optional,
timezone and times are not allowed. Example: `0000-09-01T00:00:00-00:00`
for a birthday on September 1st. `1998-09-01T00:00:00-00:00` for a birthday
on September 1st 1998. | - -### Example (as JSON) - -```json -{ - "given_name": "Amelia", - "family_name": "Earhart", - "email_address": "Amelia.Earhart@example.com", - "address": { - "address_line_1": "500 Electric Ave", - "address_line_2": "Suite 600", - "locality": "New York", - "administrative_district_level_1": "NY", - "postal_code": "10003", - "country": "US" - }, - "phone_number": "1-212-555-4240", - "reference_id": "YOUR_REFERENCE_ID", - "note": "a customer" -} -``` - +## Create Customer Request + +Defines the body parameters that can be provided in a request to the +CreateCustomer endpoint. + +### Structure + +`CreateCustomerRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `String` | Optional | The idempotency key for the request. See the [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency)
guide for more information. | +| `given_name` | `String` | Optional | The customer's given (i.e., first) name. | +| `family_name` | `String` | Optional | The customer's family (i.e., last) name. | +| `company_name` | `String` | Optional | The name of the customer's company. | +| `nickname` | `String` | Optional | A nickname for the customer. | +| `email_address` | `String` | Optional | The customer's email address. | +| `address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `phone_number` | `String` | Optional | The customer's phone number. | +| `reference_id` | `String` | Optional | An optional second ID you can set to associate the customer with an
entity in another system. | +| `note` | `String` | Optional | An optional note to associate with the customer. | +| `birthday` | `String` | Optional | The customer birthday in RFC-3339 format. Year is optional,
timezone and times are not allowed. Example: `0000-09-01T00:00:00-00:00`
for a birthday on September 1st. `1998-09-01T00:00:00-00:00` for a birthday
on September 1st 1998. | + +### Example (as JSON) + +```json +{ + "given_name": "Amelia", + "family_name": "Earhart", + "email_address": "Amelia.Earhart@example.com", + "address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "locality": "New York", + "administrative_district_level_1": "NY", + "postal_code": "10003", + "country": "US" + }, + "phone_number": "1-212-555-4240", + "reference_id": "YOUR_REFERENCE_ID", + "note": "a customer" +} +``` + diff --git a/doc/models/create-customer-response.md b/doc/models/create-customer-response.md index 232a5a57..0e4511a5 100644 --- a/doc/models/create-customer-response.md +++ b/doc/models/create-customer-response.md @@ -1,44 +1,44 @@ -## Create Customer Response - -Defines the fields that are included in the response body of -a request to the CreateCustomer endpoint. - -One of `errors` or `customer` is present in a given response (never both). - -### Structure - -`CreateCustomerResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `customer` | [`Customer Hash`](/doc/models/customer.md) | Optional | Represents one of a business's customers, which can have one or more
cards on file associated with it. | - -### Example (as JSON) - -```json -{ - "customer": { - "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", - "created_at": "2016-03-23T20:21:54.859Z", - "updated_at": "2016-03-23T20:21:54.859Z", - "given_name": "Amelia", - "family_name": "Earhart", - "email_address": "Amelia.Earhart@example.com", - "address": { - "address_line_1": "500 Electric Ave", - "address_line_2": "Suite 600", - "locality": "New York", - "administrative_district_level_1": "NY", - "postal_code": "10003", - "country": "US" - }, - "phone_number": "1-212-555-4240", - "reference_id": "YOUR_REFERENCE_ID", - "note": "a customer" - } -} -``` - +## Create Customer Response + +Defines the fields that are included in the response body of +a request to the CreateCustomer endpoint. + +One of `errors` or `customer` is present in a given response (never both). + +### Structure + +`CreateCustomerResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `customer` | [`Customer Hash`](/doc/models/customer.md) | Optional | Represents one of a business's customers, which can have one or more
cards on file associated with it. | + +### Example (as JSON) + +```json +{ + "customer": { + "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", + "created_at": "2016-03-23T20:21:54.859Z", + "updated_at": "2016-03-23T20:21:54.859Z", + "given_name": "Amelia", + "family_name": "Earhart", + "email_address": "Amelia.Earhart@example.com", + "address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "locality": "New York", + "administrative_district_level_1": "NY", + "postal_code": "10003", + "country": "US" + }, + "phone_number": "1-212-555-4240", + "reference_id": "YOUR_REFERENCE_ID", + "note": "a customer" + } +} +``` + diff --git a/doc/models/create-mobile-authorization-code-request.md b/doc/models/create-mobile-authorization-code-request.md index d57228b2..2f9d4993 100644 --- a/doc/models/create-mobile-authorization-code-request.md +++ b/doc/models/create-mobile-authorization-code-request.md @@ -1,23 +1,23 @@ -## Create Mobile Authorization Code Request - +## Create Mobile Authorization Code Request + Defines the body parameters that can be provided in a request to the -CreateMobileAuthorizationCode endpoint. - -### Structure - -`CreateMobileAuthorizationCodeRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Optional | The Square location ID the authorization code should be tied to. | - -### Example (as JSON) - -```json -{ - "location_id": "YOUR_LOCATION_ID" -} -``` - +CreateMobileAuthorizationCode endpoint. + +### Structure + +`CreateMobileAuthorizationCodeRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Optional | The Square location ID the authorization code should be tied to. | + +### Example (as JSON) + +```json +{ + "location_id": "YOUR_LOCATION_ID" +} +``` + diff --git a/doc/models/create-mobile-authorization-code-response.md b/doc/models/create-mobile-authorization-code-response.md index 0df75fe6..9bc33104 100644 --- a/doc/models/create-mobile-authorization-code-response.md +++ b/doc/models/create-mobile-authorization-code-response.md @@ -1,26 +1,26 @@ -## Create Mobile Authorization Code Response - -Defines the fields that are included in the response body of -a request to the CreateMobileAuthorizationCode endpoint. - -### Structure - -`CreateMobileAuthorizationCodeResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `authorization_code` | `String` | Optional | Generated authorization code that connects a mobile application instance to a Square account. | -| `expires_at` | `String` | Optional | The timestamp when `authorization_code` expires in [RFC 3339](https://tools.ietf.org/html/rfc3339) format, e.g., "2016-09-04T23:59:33.123Z". | -| `error` | [`Error Hash`](/doc/models/error.md) | Optional | Represents an error encountered during a request to the Connect API. | - -### Example (as JSON) - -```json -{ - "authorization_code": "YOUR_MOBILE_AUTHZ_CODE", - "expires_at": "2019-01-10T19:42:08Z" -} -``` - +## Create Mobile Authorization Code Response + +Defines the fields that are included in the response body of +a request to the CreateMobileAuthorizationCode endpoint. + +### Structure + +`CreateMobileAuthorizationCodeResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `authorization_code` | `String` | Optional | Generated authorization code that connects a mobile application instance to a Square account. | +| `expires_at` | `String` | Optional | The timestamp when `authorization_code` expires in [RFC 3339](https://tools.ietf.org/html/rfc3339) format, e.g., "2016-09-04T23:59:33.123Z". | +| `error` | [`Error Hash`](/doc/models/error.md) | Optional | Represents an error encountered during a request to the Connect API. | + +### Example (as JSON) + +```json +{ + "authorization_code": "YOUR_MOBILE_AUTHZ_CODE", + "expires_at": "2019-01-10T19:42:08Z" +} +``` + diff --git a/doc/models/create-order-request-discount.md b/doc/models/create-order-request-discount.md index bafef747..7d09ff50 100644 --- a/doc/models/create-order-request-discount.md +++ b/doc/models/create-order-request-discount.md @@ -1,31 +1,31 @@ -## Create Order Request Discount - -__Deprecated__: Please use the [OrderLineItemDiscount](./models/order-line-item-discount.md) type -in the order field of [CreateOrderRequest](./models/create-order-request.md) instead. - -Represents a discount that can apply to either a single line item or an entire order. - -### Structure - -`CreateOrderRequestDiscount` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `catalog_object_id` | `String` | Optional | Only used for catalog discounts.
The catalog object ID for an existing [CatalogDiscount](./models/catalog-discount.md).

Do not provide a value for this field if you provide values in other fields for an ad hoc discount. | -| `name` | `String` | Optional | Only used for ad hoc discounts. The discount's name. | -| `percentage` | `String` | Optional | Only used for ad hoc discounts. The percentage of the discount, as a string representation of a decimal number.

A value of `7.25` corresponds to a percentage of 7.25%. This value range between 0.0 up to 100.0 | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "catalog_object_id": null, - "name": null, - "percentage": null, - "amount_money": null -} -``` - +## Create Order Request Discount + +__Deprecated__: Please use the [OrderLineItemDiscount](#type-orderlineitemdiscount) type +in the order field of [CreateOrderRequest](#type-createorderrequest) instead. + +Represents a discount that can apply to either a single line item or an entire order. + +### Structure + +`CreateOrderRequestDiscount` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `catalog_object_id` | `String` | Optional | Only used for catalog discounts.
The catalog object ID for an existing [CatalogDiscount](#type-catalogdiscount).

Do not provide a value for this field if you provide values in other fields for an ad hoc discount. | +| `name` | `String` | Optional | Only used for ad hoc discounts. The discount's name. | +| `percentage` | `String` | Optional | Only used for ad hoc discounts. The percentage of the discount, as a string representation of a decimal number.

A value of `7.25` corresponds to a percentage of 7.25%. This value range between 0.0 up to 100.0 | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "catalog_object_id": null, + "name": null, + "percentage": null, + "amount_money": null +} +``` + diff --git a/doc/models/create-order-request-line-item.md b/doc/models/create-order-request-line-item.md index c019ee31..2431edfd 100644 --- a/doc/models/create-order-request-line-item.md +++ b/doc/models/create-order-request-line-item.md @@ -1,45 +1,45 @@ -## Create Order Request Line Item - -__Deprecated__: Please use the [OrderLineItem](./models/order-line-item.md) type in the order -field of [CreateOrderRequest](./models/create-order-request.md) instead. - -Represents a line item to include in an order. Each line item describes -a different product to purchase, with its own quantity and price details. - -Line items can either reference objects from the merchant's catalog, or can -alternatively specify a name and price instead. - -### Structure - -`CreateOrderRequestLineItem` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | Only used for ad hoc line items. The name of the line item. This value cannot exceed 500 characters.

Do not provide a value for this field if you provide a value for `catalog_object_id`. | -| `quantity` | `String` | | The quantity to purchase, as a string representation of a number.

This string must have a positive integer value. | -| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `variation_name` | `String` | Optional | Only used for ad hoc line items. The variation name of the line item. This value cannot exceed 255 characters.

If this value is not set for an ad hoc line item, the default value of `Regular` is used.

Do not provide a value for this field if you provide a value for the `catalog_object_id`. | -| `note` | `String` | Optional | The note of the line item. This value cannot exceed 500 characters. | -| `catalog_object_id` | `String` | Optional | Only used for Catalog line items.
The catalog object ID for an existing [CatalogItemVariation](./models/catalog-item-variation.md).

Do not provide a value for this field if you provide a value for `name` and `base_price_money`. | -| `modifiers` | [`Array`](/doc/models/create-order-request-modifier.md) | Optional | Only used for Catalog line items. The modifiers to include on the line item. | -| `taxes` | [`Array`](/doc/models/create-order-request-tax.md) | Optional | The taxes to include on the line item. | -| `discounts` | [`Array`](/doc/models/create-order-request-discount.md) | Optional | The discounts to include on the line item. | - -### Example (as JSON) - -```json -{ - "name": null, - "quantity": "quantity6", - "base_price_money": null, - "variation_name": null, - "note": null, - "catalog_object_id": null, - "modifiers": null, - "taxes": null, - "discounts": null -} -``` - +## Create Order Request Line Item + +__Deprecated__: Please use the [OrderLineItem](#type-orderlineitem) type in the order +field of [CreateOrderRequest](#type-createorderrequest) instead. + +Represents a line item to include in an order. Each line item describes +a different product to purchase, with its own quantity and price details. + +Line items can either reference objects from the merchant's catalog, or can +alternatively specify a name and price instead. + +### Structure + +`CreateOrderRequestLineItem` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | Only used for ad hoc line items. The name of the line item. This value cannot exceed 500 characters.

Do not provide a value for this field if you provide a value for `catalog_object_id`. | +| `quantity` | `String` | | The quantity to purchase, as a string representation of a number.

This string must have a positive integer value. | +| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `variation_name` | `String` | Optional | Only used for ad hoc line items. The variation name of the line item. This value cannot exceed 255 characters.

If this value is not set for an ad hoc line item, the default value of `Regular` is used.

Do not provide a value for this field if you provide a value for the `catalog_object_id`. | +| `note` | `String` | Optional | The note of the line item. This value cannot exceed 500 characters. | +| `catalog_object_id` | `String` | Optional | Only used for Catalog line items.
The catalog object ID for an existing [CatalogItemVariation](#type-catalogitemvariation).

Do not provide a value for this field if you provide a value for `name` and `base_price_money`. | +| `modifiers` | [`Array`](/doc/models/create-order-request-modifier.md) | Optional | Only used for Catalog line items. The modifiers to include on the line item. | +| `taxes` | [`Array`](/doc/models/create-order-request-tax.md) | Optional | The taxes to include on the line item. | +| `discounts` | [`Array`](/doc/models/create-order-request-discount.md) | Optional | The discounts to include on the line item. | + +### Example (as JSON) + +```json +{ + "name": null, + "quantity": "quantity6", + "base_price_money": null, + "variation_name": null, + "note": null, + "catalog_object_id": null, + "modifiers": null, + "taxes": null, + "discounts": null +} +``` + diff --git a/doc/models/create-order-request-modifier.md b/doc/models/create-order-request-modifier.md index 4bab1411..fe557737 100644 --- a/doc/models/create-order-request-modifier.md +++ b/doc/models/create-order-request-modifier.md @@ -1,31 +1,31 @@ -## Create Order Request Modifier - -__Deprecated__: Please use the [OrderLineItemModifier](./models/order-line-item-modifier.md) type -instead. - -Represents a modifier applied to a single line item. - -Modifiers can reference existing objects in a merchant catalog or be constructed ad hoc at the time of purchase by providing a name and price. - -### Structure - -`CreateOrderRequestModifier` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `catalog_object_id` | `String` | Optional | The catalog object ID of a [CatalogModifier](./models/catalog-modifier.md). | -| `name` | `String` | Optional | Only used for ad hoc modifiers. The name of the modifier. `name` cannot exceed 255 characters.

Do not provide a value for `name` if you provide a value for `catalog_object_id`. | -| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "catalog_object_id": null, - "name": null, - "base_price_money": null -} -``` - +## Create Order Request Modifier + +__Deprecated__: Please use the [OrderLineItemModifier](#type-orderlineitemmodifier) type +instead. + +Represents a modifier applied to a single line item. + +Modifiers can reference existing objects in a merchant catalog or be constructed ad hoc at the time of purchase by providing a name and price. + +### Structure + +`CreateOrderRequestModifier` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `catalog_object_id` | `String` | Optional | The catalog object ID of a [CatalogModifier](#type-catalogmodifier). | +| `name` | `String` | Optional | Only used for ad hoc modifiers. The name of the modifier. `name` cannot exceed 255 characters.

Do not provide a value for `name` if you provide a value for `catalog_object_id`. | +| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "catalog_object_id": null, + "name": null, + "base_price_money": null +} +``` + diff --git a/doc/models/create-order-request-tax.md b/doc/models/create-order-request-tax.md index 43587ca8..31829eb4 100644 --- a/doc/models/create-order-request-tax.md +++ b/doc/models/create-order-request-tax.md @@ -1,31 +1,31 @@ -## Create Order Request Tax - -__Deprecated__: Please use the [OrderLineItemTax](./models/order-line-item-tax.md) type in the -order field of [CreateOrderRequest](./models/create-order-request.md) instead. - -Represents a tax that can apply to either a single line item or an entire order. - -### Structure - -`CreateOrderRequestTax` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `catalog_object_id` | `String` | Optional | Only used for catalog taxes. The catalog object ID of an existing [CatalogTax](./models/catalog-tax.md).

Do not provide a value for this field if you provide values in other fields for an ad hoc tax. | -| `name` | `String` | Optional | Only used for ad hoc taxes. The tax's name.

Do not provide a value for this field if you set `catalog_object_id`. | -| `type` | [`String (Order Line Item Tax Type)`](/doc/models/order-line-item-tax-type.md) | Optional | Indicates how the tax is applied to the associated line item or order. | -| `percentage` | `String` | Optional | Only used for ad hoc taxes. The percentage of the tax, as a string representation of a decimal number.

A value of `7.25` corresponds to a percentage of 7.25%. This value range between 0.0 up to 100.0 | - -### Example (as JSON) - -```json -{ - "catalog_object_id": null, - "name": null, - "type": null, - "percentage": null -} -``` - +## Create Order Request Tax + +__Deprecated__: Please use the [OrderLineItemTax](#type-orderlineitemtax) type in the +order field of [CreateOrderRequest](#type-createorderrequest) instead. + +Represents a tax that can apply to either a single line item or an entire order. + +### Structure + +`CreateOrderRequestTax` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `catalog_object_id` | `String` | Optional | Only used for catalog taxes. The catalog object ID of an existing [CatalogTax](#type-catalogtax).

Do not provide a value for this field if you provide values in other fields for an ad hoc tax. | +| `name` | `String` | Optional | Only used for ad hoc taxes. The tax's name.

Do not provide a value for this field if you set `catalog_object_id`. | +| `type` | [`String (Order Line Item Tax Type)`](/doc/models/order-line-item-tax-type.md) | Optional | Indicates how the tax is applied to the associated line item or order. | +| `percentage` | `String` | Optional | Only used for ad hoc taxes. The percentage of the tax, as a string representation of a decimal number.

A value of `7.25` corresponds to a percentage of 7.25%. This value range between 0.0 up to 100.0 | + +### Example (as JSON) + +```json +{ + "catalog_object_id": null, + "name": null, + "type": null, + "percentage": null +} +``` + diff --git a/doc/models/create-order-request.md b/doc/models/create-order-request.md index d532f620..84e35634 100644 --- a/doc/models/create-order-request.md +++ b/doc/models/create-order-request.md @@ -1,30 +1,30 @@ -## Create Order Request - -### Structure - -`CreateOrderRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | -| `idempotency_key` | `String` | Optional | A value you specify that uniquely identifies this
order among orders you've created.

If you're unsure whether a particular order was created successfully,
you can reattempt it with the same idempotency key without
worrying about creating duplicate orders.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | -| `reference_id` | `String` | Optional | __Deprecated__: Please set the reference_id on the nested [order](./models/order.md) field
instead.

An optional ID you can associate with the order for your own
purposes (such as to associate the order with an entity ID in your
own database).

This value cannot exceed 40 characters. | -| `line_items` | [`Array`](/doc/models/create-order-request-line-item.md) | Optional | __Deprecated__: Please set the line_items on the nested [order](./models/order.md) field
instead.

The line items to associate with this order.

Each line item represents a different product to include in a purchase. | -| `taxes` | [`Array`](/doc/models/create-order-request-tax.md) | Optional | __Deprecated__: Please set the taxes on the nested [order](./models/order.md) field instead.

The taxes to include on the order. | -| `discounts` | [`Array`](/doc/models/create-order-request-discount.md) | Optional | __Deprecated__: Please set the discounts on the nested [order](./models/order.md) field instead.

The discounts to include on the order. | - -### Example (as JSON) - -```json -{ - "order": null, - "idempotency_key": null, - "reference_id": null, - "line_items": null, - "taxes": null, - "discounts": null -} -``` - +## Create Order Request + +### Structure + +`CreateOrderRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | +| `idempotency_key` | `String` | Optional | A value you specify that uniquely identifies this
order among orders you've created.

If you're unsure whether a particular order was created successfully,
you can reattempt it with the same idempotency key without
worrying about creating duplicate orders.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | +| `reference_id` | `String` | Optional | __Deprecated__: Please set the reference_id on the nested [order](#type-order) field
instead.

An optional ID you can associate with the order for your own
purposes (such as to associate the order with an entity ID in your
own database).

This value cannot exceed 40 characters. | +| `line_items` | [`Array`](/doc/models/create-order-request-line-item.md) | Optional | __Deprecated__: Please set the line_items on the nested [order](#type-order) field
instead.

The line items to associate with this order.

Each line item represents a different product to include in a purchase. | +| `taxes` | [`Array`](/doc/models/create-order-request-tax.md) | Optional | __Deprecated__: Please set the taxes on the nested [order](#type-order) field instead.

The taxes to include on the order. | +| `discounts` | [`Array`](/doc/models/create-order-request-discount.md) | Optional | __Deprecated__: Please set the discounts on the nested [order](#type-order) field instead.

The discounts to include on the order. | + +### Example (as JSON) + +```json +{ + "order": null, + "idempotency_key": null, + "reference_id": null, + "line_items": null, + "taxes": null, + "discounts": null +} +``` + diff --git a/doc/models/create-order-response.md b/doc/models/create-order-response.md index 848bef06..9736bdb9 100644 --- a/doc/models/create-order-response.md +++ b/doc/models/create-order-response.md @@ -1,236 +1,236 @@ -## Create Order Response - -Defines the fields that are included in the response body of -a request to the CreateOrder endpoint. - -One of `errors` or `order` is present in a given response (never both). - -### Structure - -`CreateOrderResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "order": { - "id": "CAISENgvlJ6jLWAzERDzjyHVybY", - "location_id": "LOCATION_ID", - "line_items": [ - { - "name": "New York Strip Steak", - "quantity": "1", - "taxes": [ - { - "name": "State Sales Tax", - "type": "ADDITIVE", - "percentage": "9", - "applied_money": { - "amount": 136, - "currency": "USD" - } - } - ], - "discounts": [ - { - "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7", - "name": "Membership Discount", - "type": "FIXED_PERCENTAGE", - "percentage": "0.5", - "applied_money": { - "amount": 8, - "currency": "USD" - }, - "scope": "ORDER" - }, - { - "name": "Labor Day Sale", - "type": "FIXED_PERCENTAGE", - "percentage": "5", - "applied_money": { - "amount": 79, - "currency": "USD" - }, - "scope": "ORDER" - } - ], - "base_price_money": { - "amount": 1599, - "currency": "USD" - }, - "gross_sales_money": { - "amount": 1599, - "currency": "USD" - }, - "total_tax_money": { - "amount": 136, - "currency": "USD" - }, - "total_discount_money": { - "amount": 87, - "currency": "USD" - }, - "total_money": { - "amount": 1648, - "currency": "USD" - } - }, - { - "name": "New York Steak", - "quantity": "2", - "catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB", - "variation_name": "Larger", - "modifiers": [ - { - "catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ", - "name": "Well", - "base_price_money": { - "amount": 50, - "currency": "USD" - }, - "total_price_money": { - "amount": 100, - "currency": "USD" - } - } - ], - "taxes": [ - { - "name": "State Sales Tax", - "type": "ADDITIVE", - "percentage": "9", - "applied_money": { - "amount": 374, - "currency": "USD" - } - } - ], - "discounts": [ - { - "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7", - "name": "Membership Discount", - "type": "FIXED_PERCENTAGE", - "percentage": "0.5", - "applied_money": { - "amount": 22, - "currency": "USD" - }, - "scope": "ORDER" - }, - { - "name": "Labor Day Sale", - "type": "FIXED_PERCENTAGE", - "percentage": "5", - "applied_money": { - "amount": 224, - "currency": "USD" - }, - "scope": "ORDER" - }, - { - "name": "Sale - $1.00 off", - "type": "FIXED_AMOUNT", - "amount_money": { - "amount": 100, - "currency": "USD" - }, - "applied_money": { - "amount": 100, - "currency": "USD" - }, - "scope": "LINE_ITEM" - } - ], - "base_price_money": { - "amount": 2200, - "currency": "USD" - }, - "gross_sales_money": { - "amount": 4500, - "currency": "USD" - }, - "total_tax_money": { - "amount": 374, - "currency": "USD" - }, - "total_discount_money": { - "amount": 346, - "currency": "USD" - }, - "total_money": { - "amount": 4528, - "currency": "USD" - } - } - ], - "taxes": [ - { - "name": "State Sales Tax", - "type": "ADDITIVE", - "percentage": "9", - "applied_money": { - "amount": 510, - "currency": "USD" - }, - "scope": "ORDER" - } - ], - "discounts": [ - { - "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7", - "name": "Membership Discount", - "type": "FIXED_PERCENTAGE", - "percentage": "0.5", - "applied_money": { - "amount": 30, - "currency": "USD" - }, - "scope": "ORDER" - }, - { - "name": "Labor Day Sale", - "type": "FIXED_PERCENTAGE", - "percentage": "5", - "applied_money": { - "amount": 303, - "currency": "USD" - }, - "scope": "ORDER" - }, - { - "name": "Sale - $1.00 off", - "type": "FIXED_AMOUNT", - "amount_money": { - "amount": 100, - "currency": "USD" - }, - "applied_money": { - "amount": 100, - "currency": "USD" - }, - "scope": "LINE_ITEM" - } - ], - "total_money": { - "amount": 6176, - "currency": "USD" - }, - "total_tax_money": { - "amount": 510, - "currency": "USD" - }, - "total_discount_money": { - "amount": 433, - "currency": "USD" - } - } -} -``` - +## Create Order Response + +Defines the fields that are included in the response body of +a request to the CreateOrder endpoint. + +One of `errors` or `order` is present in a given response (never both). + +### Structure + +`CreateOrderResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "order": { + "id": "CAISENgvlJ6jLWAzERDzjyHVybY", + "location_id": "LOCATION_ID", + "line_items": [ + { + "name": "New York Strip Steak", + "quantity": "1", + "taxes": [ + { + "name": "State Sales Tax", + "type": "ADDITIVE", + "percentage": "9", + "applied_money": { + "amount": 136, + "currency": "USD" + } + } + ], + "discounts": [ + { + "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7", + "name": "Membership Discount", + "type": "FIXED_PERCENTAGE", + "percentage": "0.5", + "applied_money": { + "amount": 8, + "currency": "USD" + }, + "scope": "ORDER" + }, + { + "name": "Labor Day Sale", + "type": "FIXED_PERCENTAGE", + "percentage": "5", + "applied_money": { + "amount": 79, + "currency": "USD" + }, + "scope": "ORDER" + } + ], + "base_price_money": { + "amount": 1599, + "currency": "USD" + }, + "gross_sales_money": { + "amount": 1599, + "currency": "USD" + }, + "total_tax_money": { + "amount": 136, + "currency": "USD" + }, + "total_discount_money": { + "amount": 87, + "currency": "USD" + }, + "total_money": { + "amount": 1648, + "currency": "USD" + } + }, + { + "name": "New York Steak", + "quantity": "2", + "catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB", + "variation_name": "Larger", + "modifiers": [ + { + "catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ", + "name": "Well", + "base_price_money": { + "amount": 50, + "currency": "USD" + }, + "total_price_money": { + "amount": 100, + "currency": "USD" + } + } + ], + "taxes": [ + { + "name": "State Sales Tax", + "type": "ADDITIVE", + "percentage": "9", + "applied_money": { + "amount": 374, + "currency": "USD" + } + } + ], + "discounts": [ + { + "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7", + "name": "Membership Discount", + "type": "FIXED_PERCENTAGE", + "percentage": "0.5", + "applied_money": { + "amount": 22, + "currency": "USD" + }, + "scope": "ORDER" + }, + { + "name": "Labor Day Sale", + "type": "FIXED_PERCENTAGE", + "percentage": "5", + "applied_money": { + "amount": 224, + "currency": "USD" + }, + "scope": "ORDER" + }, + { + "name": "Sale - $1.00 off", + "type": "FIXED_AMOUNT", + "amount_money": { + "amount": 100, + "currency": "USD" + }, + "applied_money": { + "amount": 100, + "currency": "USD" + }, + "scope": "LINE_ITEM" + } + ], + "base_price_money": { + "amount": 2200, + "currency": "USD" + }, + "gross_sales_money": { + "amount": 4500, + "currency": "USD" + }, + "total_tax_money": { + "amount": 374, + "currency": "USD" + }, + "total_discount_money": { + "amount": 346, + "currency": "USD" + }, + "total_money": { + "amount": 4528, + "currency": "USD" + } + } + ], + "taxes": [ + { + "name": "State Sales Tax", + "type": "ADDITIVE", + "percentage": "9", + "applied_money": { + "amount": 510, + "currency": "USD" + }, + "scope": "ORDER" + } + ], + "discounts": [ + { + "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7", + "name": "Membership Discount", + "type": "FIXED_PERCENTAGE", + "percentage": "0.5", + "applied_money": { + "amount": 30, + "currency": "USD" + }, + "scope": "ORDER" + }, + { + "name": "Labor Day Sale", + "type": "FIXED_PERCENTAGE", + "percentage": "5", + "applied_money": { + "amount": 303, + "currency": "USD" + }, + "scope": "ORDER" + }, + { + "name": "Sale - $1.00 off", + "type": "FIXED_AMOUNT", + "amount_money": { + "amount": 100, + "currency": "USD" + }, + "applied_money": { + "amount": 100, + "currency": "USD" + }, + "scope": "LINE_ITEM" + } + ], + "total_money": { + "amount": 6176, + "currency": "USD" + }, + "total_tax_money": { + "amount": 510, + "currency": "USD" + }, + "total_discount_money": { + "amount": 433, + "currency": "USD" + } + } +} +``` + diff --git a/doc/models/create-payment-request.md b/doc/models/create-payment-request.md index 7545d872..48f99c76 100644 --- a/doc/models/create-payment-request.md +++ b/doc/models/create-payment-request.md @@ -1,59 +1,59 @@ -## Create Payment Request - -Creates a payment from the source (nonce, card on file, etc.) - -The `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required -to enable application fees. - -For more information, see [Payments and Refunds Overview](https://developer.squareup.com/docs/payments-api/overview). - -For information about application fees in a payment, see -[Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees). - -### Structure - -`CreatePaymentRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `source_id` | `String` | | The ID for the source of funds for this payment. This can be a nonce
generated by the Payment Form or a card on file made with the Customers API. | -| `idempotency_key` | `String` | | A unique string that identifies this CreatePayment request. Keys can be any valid string but
must be unique for every CreatePayment request.

Max: 45 characters

See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `tip_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `app_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `autocomplete` | `Boolean` | Optional | If set to `true`, this payment will be completed when possible. If
set to `false`, this payment will be held in an approved state until either
explicitly completed or canceled. For more information, see
[Delayed Payments](https://developer.squareup.com/docs/payments-api/take-payments#delayed-payments).

Default: true | -| `order_id` | `String` | Optional | Associate a previously created order with this payment | -| `customer_id` | `String` | Optional | The ID of the customer associated with the payment.
Required if the `source_id` refers to a card on file created using the
Customers API. | -| `location_id` | `String` | Optional | The location ID to associate with the payment. If not specified, the default location is used. | -| `reference_id` | `String` | Optional | A user-defined ID to associate with the payment.
You can use this field to associate the payment to an entity in an external system.
For example, you might specify an order ID that is generated by a third-party shopping cart.

Limit 40 characters. | -| `verification_token` | `String` | Optional | An identifying token generated by `SqPaymentForm.verifyBuyer()`.
Verification tokens encapsulate customer device information and 3-D Secure
challenge results to indicate that Square has verified the buyer identity.

See the [SCA Overview](https://developer.squareup.com/docs/sca-overview) for more. | -| `accept_partial_authorization` | `Boolean` | Optional | If set to true and charging a Square Gift Card, a payment may be returned with
amount_money equal to less than what was requested. Example, a request for $20 when charging
a Square Gift Card with balance of $5 wil result in an APPROVED payment of $5. You may choose
to prompt the buyer for an additional payment to cover the remainder, or cancel the gift card
payment. Cannot be `true` when `autocomplete = true

For more information, see
[Partial amount with Square gift cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).

Default: false | -| `buyer_email_address` | `String` | Optional | The buyer's e-mail address | -| `billing_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `note` | `String` | Optional | An optional note to be entered by the developer when creating a payment

Limit 500 characters. | - -### Example (as JSON) - -```json -{ - "idempotency_key": "4935a656-a929-4792-b97c-8848be85c27c", - "amount_money": { - "amount": 200, - "currency": "USD" - }, - "source_id": "ccof:uIbfJXhXETSP197M3GB", - "autocomplete": true, - "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8", - "location_id": "XK3DBG77NJBFX", - "reference_id": "123456", - "note": "Brief description", - "app_fee_money": { - "amount": 10, - "currency": "USD" - } -} -``` - +## Create Payment Request + +Creates a payment from the source (nonce, card on file, etc.) + +The `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required +to enable application fees. + +For more information, see [Payments and Refunds Overview](https://developer.squareup.com/docs/payments-api/overview). + +For information about application fees in a payment, see +[Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees). + +### Structure + +`CreatePaymentRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `source_id` | `String` | | The ID for the source of funds for this payment. This can be a nonce
generated by the Payment Form or a card on file made with the Customers API. | +| `idempotency_key` | `String` | | A unique string that identifies this CreatePayment request. Keys can be any valid string but
must be unique for every CreatePayment request.

Max: 45 characters

See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `tip_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `app_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `autocomplete` | `Boolean` | Optional | If set to `true`, this payment will be completed when possible. If
set to `false`, this payment will be held in an approved state until either
explicitly completed (captured) or canceled (voided). For more information, see
[Delayed Payments](https://developer.squareup.com/docs/payments-api/take-payments#delayed-payments).

Default: true | +| `order_id` | `String` | Optional | Associate a previously created order with this payment | +| `customer_id` | `String` | Optional | The ID of the customer associated with the payment.
Required if the `source_id` refers to a card on file created using the
Customers API. | +| `location_id` | `String` | Optional | The location ID to associate with the payment. If not specified, the default location is used. | +| `reference_id` | `String` | Optional | A user-defined ID to associate with the payment.
You can use this field to associate the payment to an entity in an external system.
For example, you might specify an order ID that is generated by a third-party shopping cart.

Limit 40 characters. | +| `verification_token` | `String` | Optional | An identifying token generated by `SqPaymentForm.verifyBuyer()`.
Verification tokens encapsulate customer device information and 3-D Secure
challenge results to indicate that Square has verified the buyer identity.

See the [SCA Overview](https://developer.squareup.com/docs/sca-overview) for more. | +| `accept_partial_authorization` | `Boolean` | Optional | If set to true and charging a Square Gift Card, a payment may be returned with
amount_money equal to less than what was requested. Example, a request for $20 when charging
a Square Gift Card with balance of $5 wil result in an APPROVED payment of $5. You may choose
to prompt the buyer for an additional payment to cover the remainder, or cancel the gift card
payment. Cannot be `true` when `autocomplete = true

For more information, see
[Partial amount with Square gift cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).

Default: false | +| `buyer_email_address` | `String` | Optional | The buyer's e-mail address | +| `billing_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `note` | `String` | Optional | An optional note to be entered by the developer when creating a payment

Limit 500 characters. | + +### Example (as JSON) + +```json +{ + "idempotency_key": "4935a656-a929-4792-b97c-8848be85c27c", + "amount_money": { + "amount": 200, + "currency": "USD" + }, + "source_id": "ccof:uIbfJXhXETSP197M3GB", + "autocomplete": true, + "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8", + "location_id": "XK3DBG77NJBFX", + "reference_id": "123456", + "note": "Brief description", + "app_fee_money": { + "amount": 10, + "currency": "USD" + } +} +``` + diff --git a/doc/models/create-payment-response.md b/doc/models/create-payment-response.md index 7c5717af..c1c49503 100644 --- a/doc/models/create-payment-response.md +++ b/doc/models/create-payment-response.md @@ -1,64 +1,64 @@ -## Create Payment Response - -Defines the fields that are included in the response body of -a request to the [CreatePayment](/doc/payments.md#createpayment) endpoint. - -Note: if there are errors processing the request, the payment field may not be -present, or it may be present with a status of `FAILED`. - -### Structure - -`CreatePaymentResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `payment` | [`Payment Hash`](/doc/models/payment.md) | Optional | Represents a payment processed by the Square API. | - -### Example (as JSON) - -```json -{ - "payment": { - "id": "iqrBxAil6rmDtr7cak9g9WO8uaB", - "created_at": "2019-07-10T13:23:49.154Z", - "updated_at": "2019-07-10T13:23:49.446Z", - "amount_money": { - "amount": 200, - "currency": "USD" - }, - "app_fee_money": { - "amount": 10, - "currency": "USD" - }, - "total_money": { - "amount": 200, - "currency": "USD" - }, - "status": "COMPLETED", - "source_type": "CARD", - "card_details": { - "status": "CAPTURED", - "card": { - "card_brand": "VISA", - "last_4": "2796", - "exp_month": 7, - "exp_year": 2026, - "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw" - }, - "entry_method": "ON_FILE", - "cvv_status": "CVV_ACCEPTED", - "avs_status": "AVS_ACCEPTED", - "auth_result_code": "nsAyY2" - }, - "location_id": "XK3DBG77NJBFX", - "order_id": "qHkNOb03hMgEgoP3gyzFBDY3cg4F", - "reference_id": "123456", - "note": "Brief description", - "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8" - } -} -``` - +## Create Payment Response + +Defines the fields that are included in the response body of +a request to the [CreatePayment](#endpoint-payments-createpayment) endpoint. + +Note: if there are errors processing the request, the payment field may not be +present, or it may be present with a status of `FAILED`. + +### Structure + +`CreatePaymentResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `payment` | [`Payment Hash`](/doc/models/payment.md) | Optional | Represents a payment processed by the Square API. | + +### Example (as JSON) + +```json +{ + "payment": { + "id": "iqrBxAil6rmDtr7cak9g9WO8uaB", + "created_at": "2019-07-10T13:23:49.154Z", + "updated_at": "2019-07-10T13:23:49.446Z", + "amount_money": { + "amount": 200, + "currency": "USD" + }, + "app_fee_money": { + "amount": 10, + "currency": "USD" + }, + "total_money": { + "amount": 200, + "currency": "USD" + }, + "status": "COMPLETED", + "source_type": "CARD", + "card_details": { + "status": "CAPTURED", + "card": { + "card_brand": "VISA", + "last_4": "2796", + "exp_month": 7, + "exp_year": 2026, + "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw" + }, + "entry_method": "ON_FILE", + "cvv_status": "CVV_ACCEPTED", + "avs_status": "AVS_ACCEPTED", + "auth_result_code": "nsAyY2" + }, + "location_id": "XK3DBG77NJBFX", + "order_id": "qHkNOb03hMgEgoP3gyzFBDY3cg4F", + "reference_id": "123456", + "note": "Brief description", + "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8" + } +} +``` + diff --git a/doc/models/create-refund-request.md b/doc/models/create-refund-request.md index 1ea4abcb..3ae62c53 100644 --- a/doc/models/create-refund-request.md +++ b/doc/models/create-refund-request.md @@ -1,34 +1,34 @@ -## Create Refund Request - -Defines the body parameters that can be included in -a request to the [CreateRefund](#endpoint-createrefund) endpoint. - -Deprecated - recommend using [RefundPayment](/doc/refunds.md#refundpayment) - -### Structure - -`CreateRefundRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `idempotency_key` | `String` | | A value you specify that uniquely identifies this
refund among refunds you've created for the tender.

If you're unsure whether a particular refund succeeded,
you can reattempt it with the same idempotency key without
worrying about duplicating the refund.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | -| `tender_id` | `String` | | The ID of the tender to refund.

A [`Transaction`](#type-transaction) has one or more `tenders` (i.e., methods
of payment) associated with it, and you refund each tender separately with
the Connect API. | -| `reason` | `String` | Optional | A description of the reason for the refund.

Default value: `Refund via API` | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "idempotency_key": "86ae1696-b1e3-4328-af6d-f1e04d947ad2", - "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF", - "reason": "a reason", - "amount_money": { - "amount": 100, - "currency": "USD" - } -} -``` - +## Create Refund Request + +Defines the body parameters that can be included in +a request to the [CreateRefund](#endpoint-createrefund) endpoint. + +Deprecated - recommend using [RefundPayment](#endpoint-refunds-refundpayment) + +### Structure + +`CreateRefundRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `String` | | A value you specify that uniquely identifies this
refund among refunds you've created for the tender.

If you're unsure whether a particular refund succeeded,
you can reattempt it with the same idempotency key without
worrying about duplicating the refund.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | +| `tender_id` | `String` | | The ID of the tender to refund.

A [`Transaction`](#type-transaction) has one or more `tenders` (i.e., methods
of payment) associated with it, and you refund each tender separately with
the Connect API. | +| `reason` | `String` | Optional | A description of the reason for the refund.

Default value: `Refund via API` | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "idempotency_key": "86ae1696-b1e3-4328-af6d-f1e04d947ad2", + "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF", + "reason": "a reason", + "amount_money": { + "amount": 100, + "currency": "USD" + } +} +``` + diff --git a/doc/models/create-refund-response.md b/doc/models/create-refund-response.md index 29dfda95..bda0786b 100644 --- a/doc/models/create-refund-response.md +++ b/doc/models/create-refund-response.md @@ -1,49 +1,49 @@ -## Create Refund Response - -Defines the fields that are included in the response body of -a request to the [CreateRefund](#endpoint-createrefund) endpoint. - -One of `errors` or `refund` is present in a given response (never both). - -### Structure - -`CreateRefundResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `refund` | [`Refund Hash`](/doc/models/refund.md) | Optional | Represents a refund processed for a Square transaction. | - -### Example (as JSON) - -```json -{ - "refund": { - "id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW", - "location_id": "18YC4JDH91E1H", - "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", - "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF", - "created_at": "2016-02-12T00:28:18Z", - "reason": "some reason", - "amount_money": { - "amount": 100, - "currency": "USD" - }, - "additional_recipients": [ - { - "location_id": "057P5VYJ4A5X1", - "description": "Application fees", - "amount_money": { - "amount": 10, - "currency": "USD" - }, - "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF" - } - ], - "status": "PENDING" - } -} -``` - +## Create Refund Response + +Defines the fields that are included in the response body of +a request to the [CreateRefund](#endpoint-createrefund) endpoint. + +One of `errors` or `refund` is present in a given response (never both). + +### Structure + +`CreateRefundResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `refund` | [`Refund Hash`](/doc/models/refund.md) | Optional | Represents a refund processed for a Square transaction. | + +### Example (as JSON) + +```json +{ + "refund": { + "id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW", + "location_id": "18YC4JDH91E1H", + "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", + "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF", + "created_at": "2016-02-12T00:28:18Z", + "reason": "some reason", + "amount_money": { + "amount": 100, + "currency": "USD" + }, + "additional_recipients": [ + { + "location_id": "057P5VYJ4A5X1", + "description": "Application fees", + "amount_money": { + "amount": 10, + "currency": "USD" + }, + "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF" + } + ], + "status": "PENDING" + } +} +``` + diff --git a/doc/models/create-shift-request.md b/doc/models/create-shift-request.md index 82dda478..5d0d737a 100644 --- a/doc/models/create-shift-request.md +++ b/doc/models/create-shift-request.md @@ -1,46 +1,46 @@ -## Create Shift Request - -Represents a request to create a `Shift` - -### Structure - -`CreateShiftRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `idempotency_key` | `String` | Optional | Unique string value to insure the idempotency of the operation. | -| `shift` | [`Shift Hash`](/doc/models/shift.md) | | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. | - -### Example (as JSON) - -```json -{ - "idempotency_key": "HIDSNG5KS478L", - "shift": { - "employee_id": "ormj0jJJZ5OZIzxrZYJI", - "location_id": "PAA1RJZZKXBFG", - "start_at": "2019-01-25T03:11:00-05:00", - "end_at": "2019-01-25T13:11:00-05:00", - "wage": { - "title": "Barista", - "hourly_rate": { - "amount": 1100, - "currency": "USD" - } - }, - "breaks": [ - { - "start_at": "2019-01-25T06:11:00-05:00", - "end_at": "2019-01-25T06:16:00-05:00", - "break_type_id": "REGS1EQR1TPZ5", - "name": "Tea Break", - "expected_duration": "PT5M", - "is_paid": true - } - ] - } -} -``` - +## Create Shift Request + +Represents a request to create a `Shift` + +### Structure + +`CreateShiftRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `String` | Optional | Unique string value to insure the idempotency of the operation. | +| `shift` | [`Shift Hash`](/doc/models/shift.md) | | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. | + +### Example (as JSON) + +```json +{ + "idempotency_key": "HIDSNG5KS478L", + "shift": { + "employee_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-25T03:11:00-05:00", + "end_at": "2019-01-25T13:11:00-05:00", + "wage": { + "title": "Barista", + "hourly_rate": { + "amount": 1100, + "currency": "USD" + } + }, + "breaks": [ + { + "start_at": "2019-01-25T06:11:00-05:00", + "end_at": "2019-01-25T06:16:00-05:00", + "break_type_id": "REGS1EQR1TPZ5", + "name": "Tea Break", + "expected_duration": "PT5M", + "is_paid": true + } + ] + } +} +``` + diff --git a/doc/models/create-shift-response.md b/doc/models/create-shift-response.md index c6e323da..c3cfce54 100644 --- a/doc/models/create-shift-response.md +++ b/doc/models/create-shift-response.md @@ -1,54 +1,54 @@ -## Create Shift Response - -The response to the request to create a `Shift`. Contains -the created `Shift` object. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`CreateShiftResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `shift` | [`Shift Hash`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "shift": { - "id": "K0YH4CV5462JB", - "employee_id": "ormj0jJJZ5OZIzxrZYJI", - "location_id": "PAA1RJZZKXBFG", - "timezone": "America/New_York", - "start_at": "2019-01-25T03:11:00-05:00", - "end_at": "2019-01-25T13:11:00-05:00", - "wage": { - "title": "Barista", - "hourly_rate": { - "amount": 1100, - "currency": "USD" - } - }, - "breaks": [ - { - "id": "X7GAQYVVRRG6P", - "start_at": "2019-01-25T06:11:00-05:00", - "end_at": "2019-01-25T06:16:00-05:00", - "break_type_id": "REGS1EQR1TPZ5", - "name": "Tea Break", - "expected_duration": "PT5M", - "is_paid": true - } - ], - "status": "CLOSED", - "version": 1, - "created_at": "2019-02-28T00:39:02Z", - "updated_at": "2019-02-28T00:39:02Z" - } -} -``` - +## Create Shift Response + +The response to the request to create a `Shift`. Contains +the created `Shift` object. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`CreateShiftResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `shift` | [`Shift Hash`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "shift": { + "id": "K0YH4CV5462JB", + "employee_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "timezone": "America/New_York", + "start_at": "2019-01-25T03:11:00-05:00", + "end_at": "2019-01-25T13:11:00-05:00", + "wage": { + "title": "Barista", + "hourly_rate": { + "amount": 1100, + "currency": "USD" + } + }, + "breaks": [ + { + "id": "X7GAQYVVRRG6P", + "start_at": "2019-01-25T06:11:00-05:00", + "end_at": "2019-01-25T06:16:00-05:00", + "break_type_id": "REGS1EQR1TPZ5", + "name": "Tea Break", + "expected_duration": "PT5M", + "is_paid": true + } + ], + "status": "CLOSED", + "version": 1, + "created_at": "2019-02-28T00:39:02Z", + "updated_at": "2019-02-28T00:39:02Z" + } +} +``` + diff --git a/doc/models/currency.md b/doc/models/currency.md index 21a3026e..0722c5c6 100644 --- a/doc/models/currency.md +++ b/doc/models/currency.md @@ -1,195 +1,195 @@ -## Currency - +## Currency + Indicates the associated currency for an amount of money. Values correspond -to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). - -### Enumeration - -`Currency` - -### Fields - -| Name | Description | -| --- | --- | -| `UNKNOWN_CURRENCY` | - | -| `AED` | - | -| `AFN` | - | -| `ALL` | - | -| `AMD` | - | -| `ANG` | - | -| `AOA` | - | -| `ARS` | - | -| `AUD` | - | -| `AWG` | - | -| `AZN` | - | -| `BAM` | - | -| `BBD` | - | -| `BDT` | - | -| `BGN` | - | -| `BHD` | - | -| `BIF` | - | -| `BMD` | - | -| `BND` | - | -| `BOB` | - | -| `BOV` | - | -| `BRL` | - | -| `BSD` | - | -| `BTN` | - | -| `BWP` | - | -| `BYR` | - | -| `BZD` | - | -| `CAD` | - | -| `CDF` | - | -| `CHE` | - | -| `CHF` | - | -| `CHW` | - | -| `CLF` | - | -| `CLP` | - | -| `CNY` | - | -| `COP` | - | -| `COU` | - | -| `CRC` | - | -| `CUC` | - | -| `CUP` | - | -| `CVE` | - | -| `CZK` | - | -| `DJF` | - | -| `DKK` | - | -| `DOP` | - | -| `DZD` | - | -| `EGP` | - | -| `ERN` | - | -| `ETB` | - | -| `EUR` | - | -| `FJD` | - | -| `FKP` | - | -| `GBP` | - | -| `GEL` | - | -| `GHS` | - | -| `GIP` | - | -| `GMD` | - | -| `GNF` | - | -| `GTQ` | - | -| `GYD` | - | -| `HKD` | - | -| `HNL` | - | -| `HRK` | - | -| `HTG` | - | -| `HUF` | - | -| `IDR` | - | -| `ILS` | - | -| `INR` | - | -| `IQD` | - | -| `IRR` | - | -| `ISK` | - | -| `JMD` | - | -| `JOD` | - | -| `JPY` | - | -| `KES` | - | -| `KGS` | - | -| `KHR` | - | -| `KMF` | - | -| `KPW` | - | -| `KRW` | - | -| `KWD` | - | -| `KYD` | - | -| `KZT` | - | -| `LAK` | - | -| `LBP` | - | -| `LKR` | - | -| `LRD` | - | -| `LSL` | - | -| `LTL` | - | -| `LVL` | - | -| `LYD` | - | -| `MAD` | - | -| `MDL` | - | -| `MGA` | - | -| `MKD` | - | -| `MMK` | - | -| `MNT` | - | -| `MOP` | - | -| `MRO` | - | -| `MUR` | - | -| `MVR` | - | -| `MWK` | - | -| `MXN` | - | -| `MXV` | - | -| `MYR` | - | -| `MZN` | - | -| `NAD` | - | -| `NGN` | - | -| `NIO` | - | -| `NOK` | - | -| `NPR` | - | -| `NZD` | - | -| `OMR` | - | -| `PAB` | - | -| `PEN` | - | -| `PGK` | - | -| `PHP` | - | -| `PKR` | - | -| `PLN` | - | -| `PYG` | - | -| `QAR` | - | -| `RON` | - | -| `RSD` | - | -| `RUB` | - | -| `RWF` | - | -| `SAR` | - | -| `SBD` | - | -| `SCR` | - | -| `SDG` | - | -| `SEK` | - | -| `SGD` | - | -| `SHP` | - | -| `SLL` | - | -| `SOS` | - | -| `SRD` | - | -| `SSP` | - | -| `STD` | - | -| `SVC` | - | -| `SYP` | - | -| `SZL` | - | -| `THB` | - | -| `TJS` | - | -| `TMT` | - | -| `TND` | - | -| `TOP` | - | -| `TRY` | - | -| `TTD` | - | -| `TWD` | - | -| `TZS` | - | -| `UAH` | - | -| `UGX` | - | -| `USD` | - | -| `USN` | - | -| `USS` | - | -| `UYI` | - | -| `UYU` | - | -| `UZS` | - | -| `VEF` | - | -| `VND` | - | -| `VUV` | - | -| `WST` | - | -| `XAF` | - | -| `XAG` | - | -| `XAU` | - | -| `XBA` | - | -| `XBB` | - | -| `XBC` | - | -| `XBD` | - | -| `XCD` | - | -| `XDR` | - | -| `XOF` | - | -| `XPD` | - | -| `XPF` | - | -| `XPT` | - | -| `XTS` | - | -| `XXX` | - | -| `YER` | - | -| `ZAR` | - | -| `ZMK` | - | -| `ZMW` | - | -| `BTC` | - | - +to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). + +### Enumeration + +`Currency` + +### Fields + +| Name | Description | +| --- | --- | +| `UNKNOWN_CURRENCY` | - | +| `AED` | - | +| `AFN` | - | +| `ALL` | - | +| `AMD` | - | +| `ANG` | - | +| `AOA` | - | +| `ARS` | - | +| `AUD` | - | +| `AWG` | - | +| `AZN` | - | +| `BAM` | - | +| `BBD` | - | +| `BDT` | - | +| `BGN` | - | +| `BHD` | - | +| `BIF` | - | +| `BMD` | - | +| `BND` | - | +| `BOB` | - | +| `BOV` | - | +| `BRL` | - | +| `BSD` | - | +| `BTN` | - | +| `BWP` | - | +| `BYR` | - | +| `BZD` | - | +| `CAD` | - | +| `CDF` | - | +| `CHE` | - | +| `CHF` | - | +| `CHW` | - | +| `CLF` | - | +| `CLP` | - | +| `CNY` | - | +| `COP` | - | +| `COU` | - | +| `CRC` | - | +| `CUC` | - | +| `CUP` | - | +| `CVE` | - | +| `CZK` | - | +| `DJF` | - | +| `DKK` | - | +| `DOP` | - | +| `DZD` | - | +| `EGP` | - | +| `ERN` | - | +| `ETB` | - | +| `EUR` | - | +| `FJD` | - | +| `FKP` | - | +| `GBP` | - | +| `GEL` | - | +| `GHS` | - | +| `GIP` | - | +| `GMD` | - | +| `GNF` | - | +| `GTQ` | - | +| `GYD` | - | +| `HKD` | - | +| `HNL` | - | +| `HRK` | - | +| `HTG` | - | +| `HUF` | - | +| `IDR` | - | +| `ILS` | - | +| `INR` | - | +| `IQD` | - | +| `IRR` | - | +| `ISK` | - | +| `JMD` | - | +| `JOD` | - | +| `JPY` | - | +| `KES` | - | +| `KGS` | - | +| `KHR` | - | +| `KMF` | - | +| `KPW` | - | +| `KRW` | - | +| `KWD` | - | +| `KYD` | - | +| `KZT` | - | +| `LAK` | - | +| `LBP` | - | +| `LKR` | - | +| `LRD` | - | +| `LSL` | - | +| `LTL` | - | +| `LVL` | - | +| `LYD` | - | +| `MAD` | - | +| `MDL` | - | +| `MGA` | - | +| `MKD` | - | +| `MMK` | - | +| `MNT` | - | +| `MOP` | - | +| `MRO` | - | +| `MUR` | - | +| `MVR` | - | +| `MWK` | - | +| `MXN` | - | +| `MXV` | - | +| `MYR` | - | +| `MZN` | - | +| `NAD` | - | +| `NGN` | - | +| `NIO` | - | +| `NOK` | - | +| `NPR` | - | +| `NZD` | - | +| `OMR` | - | +| `PAB` | - | +| `PEN` | - | +| `PGK` | - | +| `PHP` | - | +| `PKR` | - | +| `PLN` | - | +| `PYG` | - | +| `QAR` | - | +| `RON` | - | +| `RSD` | - | +| `RUB` | - | +| `RWF` | - | +| `SAR` | - | +| `SBD` | - | +| `SCR` | - | +| `SDG` | - | +| `SEK` | - | +| `SGD` | - | +| `SHP` | - | +| `SLL` | - | +| `SOS` | - | +| `SRD` | - | +| `SSP` | - | +| `STD` | - | +| `SVC` | - | +| `SYP` | - | +| `SZL` | - | +| `THB` | - | +| `TJS` | - | +| `TMT` | - | +| `TND` | - | +| `TOP` | - | +| `TRY` | - | +| `TTD` | - | +| `TWD` | - | +| `TZS` | - | +| `UAH` | - | +| `UGX` | - | +| `USD` | - | +| `USN` | - | +| `USS` | - | +| `UYI` | - | +| `UYU` | - | +| `UZS` | - | +| `VEF` | - | +| `VND` | - | +| `VUV` | - | +| `WST` | - | +| `XAF` | - | +| `XAG` | - | +| `XAU` | - | +| `XBA` | - | +| `XBB` | - | +| `XBC` | - | +| `XBD` | - | +| `XCD` | - | +| `XDR` | - | +| `XOF` | - | +| `XPD` | - | +| `XPF` | - | +| `XPT` | - | +| `XTS` | - | +| `XXX` | - | +| `YER` | - | +| `ZAR` | - | +| `ZMK` | - | +| `ZMW` | - | +| `BTC` | - | + diff --git a/doc/models/customer-creation-source-filter.md b/doc/models/customer-creation-source-filter.md index 70a82de0..daad3234 100644 --- a/doc/models/customer-creation-source-filter.md +++ b/doc/models/customer-creation-source-filter.md @@ -1,28 +1,28 @@ -## Customer Creation Source Filter - -Creation source filter. - -If one or more creation sources are set, customer profiles are included in, -or excluded from, the result if they match at least one of the filter -criteria. - -### Structure - -`CustomerCreationSourceFilter` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `values` | [`Array`](/doc/models/customer-creation-source.md) | Optional | The list of creation sources used as filtering criteria.
See [CustomerCreationSource](./models/customer-creation-source.md) for possible values | -| `rule` | [`String (Customer Inclusion Exclusion)`](/doc/models/customer-inclusion-exclusion.md) | Optional | Indicates whether customers should be included in, or excluded from,
the result set when they match the filtering criteria. | - -### Example (as JSON) - -```json -{ - "values": null, - "rule": null -} -``` - +## Customer Creation Source Filter + +Creation source filter. + +If one or more creation sources are set, customer profiles are included in, +or excluded from, the result if they match at least one of the filter +criteria. + +### Structure + +`CustomerCreationSourceFilter` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `values` | [`Array`](/doc/models/customer-creation-source.md) | Optional | The list of creation sources used as filtering criteria.
See [CustomerCreationSource](#type-customercreationsource) for possible values | +| `rule` | [`String (Customer Inclusion Exclusion)`](/doc/models/customer-inclusion-exclusion.md) | Optional | Indicates whether customers should be included in, or excluded from,
the result set when they match the filtering criteria. | + +### Example (as JSON) + +```json +{ + "values": null, + "rule": null +} +``` + diff --git a/doc/models/customer-creation-source.md b/doc/models/customer-creation-source.md index 0cda0ef1..6a27ad55 100644 --- a/doc/models/customer-creation-source.md +++ b/doc/models/customer-creation-source.md @@ -1,32 +1,32 @@ -## Customer Creation Source - -Indicates the method used to create the customer profile. - -### Enumeration - -`CustomerCreationSource` - -### Fields - -| Name | Description | -| --- | --- | -| `OTHER` | Default creation source. Typically used for backward/future
compatibility when the original source of a customer profile is
unrecognized. For example, when older clients do not support newer
source types. | -| `APPOINTMENTS` | Customer profile created automatically when an appointment
was scheduled. | -| `COUPON` | Customer profile created automatically when a coupon was issued
using Square Point of Sale. | -| `DELETION_RECOVERY` | Customer profile restored through Square's deletion recovery
process. | -| `DIRECTORY` | Customer profile created manually through Square Dashboard or
Point of Sale application. | -| `EGIFTING` | Customer profile created automatically when a gift card was
issued using Square Point of Sale. Customer profiles are created for
both the purchaser and the recipient of the gift card. | -| `EMAIL_COLLECTION` | Customer profile created through Square Point of Sale when
signing up for marketing emails during checkout. | -| `FEEDBACK` | Customer profile created automatically when providing feedback
through a digital receipt. | -| `IMPORT` | Customer profile created automatically when importing customer
data through Square Dashboard. | -| `INVOICES` | Customer profile created automatically during an invoice payment. | -| `LOYALTY` | Customer profile created automatically when customers provide a
phone number for loyalty reward programs during checkout. | -| `MARKETING` | Customer profile created as the result of a campaign managed
through Square’s Facebook integration. | -| `MERGE` | Customer profile created as the result of explicitly merging
multiple customer profiles through the Square Dashboard or Point of
Sale application. | -| `ONLINE_STORE` | Customer profile created through Square's Online Store solution
(legacy service). | -| `INSTANT_PROFILE` | Customer profile created automatically as the result of a successful
transaction that did not explicitly link to an existing customer profile. | -| `TERMINAL` | Customer profile created through Square's Virtual Terminal. | -| `THIRD_PARTY` | Customer profile created through a Square API call. | -| `THIRD_PARTY_IMPORT` | Customer profile created by a third-party product and imported
through an official integration. | -| `UNMERGE_RECOVERY` | Customer profile restored through Square's unmerge recovery
process. | - +## Customer Creation Source + +Indicates the method used to create the customer profile. + +### Enumeration + +`CustomerCreationSource` + +### Fields + +| Name | Description | +| --- | --- | +| `OTHER` | Default creation source. Typically used for backward/future
compatibility when the original source of a customer profile is
unrecognized. For example, when older clients do not support newer
source types. | +| `APPOINTMENTS` | Customer profile created automatically when an appointment
was scheduled. | +| `COUPON` | Customer profile created automatically when a coupon was issued
using Square Point of Sale. | +| `DELETION_RECOVERY` | Customer profile restored through Square's deletion recovery
process. | +| `DIRECTORY` | Customer profile created manually through Square Dashboard or
Point of Sale application. | +| `EGIFTING` | Customer profile created automatically when a gift card was
issued using Square Point of Sale. Customer profiles are created for
both the purchaser and the recipient of the gift card. | +| `EMAIL_COLLECTION` | Customer profile created through Square Point of Sale when
signing up for marketing emails during checkout. | +| `FEEDBACK` | Customer profile created automatically when providing feedback
through a digital receipt. | +| `IMPORT` | Customer profile created automatically when importing customer
data through Square Dashboard. | +| `INVOICES` | Customer profile created automatically during an invoice payment. | +| `LOYALTY` | Customer profile created automatically when customers provide a
phone number for loyalty reward programs during checkout. | +| `MARKETING` | Customer profile created as the result of a campaign managed
through Square’s Facebook integration. | +| `MERGE` | Customer profile created as the result of explicitly merging
multiple customer profiles through the Square Dashboard or Point of
Sale application. | +| `ONLINE_STORE` | Customer profile created through Square's Online Store solution
(legacy service). | +| `INSTANT_PROFILE` | Customer profile created automatically as the result of a successful
transaction that did not explicitly link to an existing customer profile. | +| `TERMINAL` | Customer profile created through Square's Virtual Terminal. | +| `THIRD_PARTY` | Customer profile created through a Square API call. | +| `THIRD_PARTY_IMPORT` | Customer profile created by a third-party product and imported
through an official integration. | +| `UNMERGE_RECOVERY` | Customer profile restored through Square's unmerge recovery
process. | + diff --git a/doc/models/customer-filter.md b/doc/models/customer-filter.md index 12cf06d6..8d5bb0c4 100644 --- a/doc/models/customer-filter.md +++ b/doc/models/customer-filter.md @@ -1,27 +1,27 @@ -## Customer Filter - -Represents a set of [`CustomerQuery`](#type-customerquery) filters used -to limit the set of Customers returned by [`SearchCustomers`](/doc/customers.md#seachcustomers). - -### Structure - -`CustomerFilter` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `creation_source` | [`Customer Creation Source Filter Hash`](/doc/models/customer-creation-source-filter.md) | Optional | Creation source filter.

If one or more creation sources are set, customer profiles are included in,
or excluded from, the result if they match at least one of the filter
criteria. | -| `created_at` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | -| `updated_at` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | - -### Example (as JSON) - -```json -{ - "creation_source": null, - "created_at": null, - "updated_at": null -} -``` - +## Customer Filter + +Represents a set of [`CustomerQuery`](#type-customerquery) filters used +to limit the set of Customers returned by [`SearchCustomers`](#endpoint-customers-seachcustomers). + +### Structure + +`CustomerFilter` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `creation_source` | [`Customer Creation Source Filter Hash`](/doc/models/customer-creation-source-filter.md) | Optional | Creation source filter.

If one or more creation sources are set, customer profiles are included in,
or excluded from, the result if they match at least one of the filter
criteria. | +| `created_at` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | +| `updated_at` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | + +### Example (as JSON) + +```json +{ + "creation_source": null, + "created_at": null, + "updated_at": null +} +``` + diff --git a/doc/models/customer-group-info.md b/doc/models/customer-group-info.md index a7cdf323..3d9d1a48 100644 --- a/doc/models/customer-group-info.md +++ b/doc/models/customer-group-info.md @@ -1,24 +1,24 @@ -## Customer Group Info - -Contains some brief information about a customer group with its identifier included. - -### Structure - -`CustomerGroupInfo` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `id` | `String` | The ID of the customer group. | -| `name` | `String` | The name of the customer group. | - -### Example (as JSON) - -```json -{ - "id": "id0", - "name": "name0" -} -``` - +## Customer Group Info + +Contains some brief information about a customer group with its identifier included. + +### Structure + +`CustomerGroupInfo` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `id` | `String` | The ID of the customer group. | +| `name` | `String` | The name of the customer group. | + +### Example (as JSON) + +```json +{ + "id": "id0", + "name": "name0" +} +``` + diff --git a/doc/models/customer-inclusion-exclusion.md b/doc/models/customer-inclusion-exclusion.md index 08f98e6f..c4ec5830 100644 --- a/doc/models/customer-inclusion-exclusion.md +++ b/doc/models/customer-inclusion-exclusion.md @@ -1,16 +1,16 @@ -## Customer Inclusion Exclusion - +## Customer Inclusion Exclusion + Indicates whether customers should be included in, or excluded from, -the result set when they match the filtering criteria. - -### Enumeration - -`CustomerInclusionExclusion` - -### Fields - -| Name | Description | -| --- | --- | -| `INCLUDE` | Customers should be included in the result set when they match the
filtering criteria. | -| `EXCLUDE` | Customers should be excluded from the result set when they match
the filtering criteria. | - +the result set when they match the filtering criteria. + +### Enumeration + +`CustomerInclusionExclusion` + +### Fields + +| Name | Description | +| --- | --- | +| `INCLUDE` | Customers should be included in the result set when they match the
filtering criteria. | +| `EXCLUDE` | Customers should be excluded from the result set when they match
the filtering criteria. | + diff --git a/doc/models/customer-preferences.md b/doc/models/customer-preferences.md index 089d1bfb..05f856a3 100644 --- a/doc/models/customer-preferences.md +++ b/doc/models/customer-preferences.md @@ -1,22 +1,22 @@ -## Customer Preferences - -Represents a particular customer's preferences. - -### Structure - -`CustomerPreferences` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `email_unsubscribed` | `Boolean` | Optional | The customer has unsubscribed from receiving marketing campaign emails. | - -### Example (as JSON) - -```json -{ - "email_unsubscribed": null -} -``` - +## Customer Preferences + +Represents a particular customer's preferences. + +### Structure + +`CustomerPreferences` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `email_unsubscribed` | `Boolean` | Optional | The customer has unsubscribed from receiving marketing campaign emails. | + +### Example (as JSON) + +```json +{ + "email_unsubscribed": null +} +``` + diff --git a/doc/models/customer-query.md b/doc/models/customer-query.md index bea5d35d..88611e33 100644 --- a/doc/models/customer-query.md +++ b/doc/models/customer-query.md @@ -1,25 +1,25 @@ -## Customer Query - -Represents a query (filtering and sorting criteria) used to search -for customer profiles. - -### Structure - -`CustomerQuery` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `filter` | [`Customer Filter Hash`](/doc/models/customer-filter.md) | Optional | Represents a set of [`CustomerQuery`](#type-customerquery) filters used
to limit the set of Customers returned by [`SearchCustomers`](/doc/customers.md#seachcustomers). | -| `sort` | [`Customer Sort Hash`](/doc/models/customer-sort.md) | Optional | Indicates the field to use for sorting customer profiles. For example,
by total money spent with the merchant or the date of their first purchase. | - -### Example (as JSON) - -```json -{ - "filter": null, - "sort": null -} -``` - +## Customer Query + +Represents a query (filtering and sorting criteria) used to search +for customer profiles. + +### Structure + +`CustomerQuery` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `filter` | [`Customer Filter Hash`](/doc/models/customer-filter.md) | Optional | Represents a set of [`CustomerQuery`](#type-customerquery) filters used
to limit the set of Customers returned by [`SearchCustomers`](#endpoint-customers-seachcustomers). | +| `sort` | [`Customer Sort Hash`](/doc/models/customer-sort.md) | Optional | Indicates the field to use for sorting customer profiles. For example,
by total money spent with the merchant or the date of their first purchase. | + +### Example (as JSON) + +```json +{ + "filter": null, + "sort": null +} +``` + diff --git a/doc/models/customer-sort-field.md b/doc/models/customer-sort-field.md index f096570e..ff72e087 100644 --- a/doc/models/customer-sort-field.md +++ b/doc/models/customer-sort-field.md @@ -1,15 +1,15 @@ -## Customer Sort Field - -Indicates the sort criteria for a list of Customers. - -### Enumeration - -`CustomerSortField` - -### Fields - -| Name | Description | -| --- | --- | -| `DEFAULT` | Use the default sort. By default, Customers are sorted
alphanumerically by concatenating `given_name` and `family_name`. If
neither name field is set, string comparison is performed using one of the
remaining fields in the following order: `company_name`, `email`,
`phone_number`. | -| `CREATED_AT` | Sort Customers by their creation date (`created_at`). | - +## Customer Sort Field + +Indicates the sort criteria for a list of Customers. + +### Enumeration + +`CustomerSortField` + +### Fields + +| Name | Description | +| --- | --- | +| `DEFAULT` | Use the default sort. By default, Customers are sorted
alphanumerically by concatenating `given_name` and `family_name`. If
neither name field is set, string comparison is performed using one of the
remaining fields in the following order: `company_name`, `email`,
`phone_number`. | +| `CREATED_AT` | Sort Customers by their creation date (`created_at`). | + diff --git a/doc/models/customer-sort.md b/doc/models/customer-sort.md index 28d5c754..00c1fd86 100644 --- a/doc/models/customer-sort.md +++ b/doc/models/customer-sort.md @@ -1,25 +1,25 @@ -## Customer Sort - -Indicates the field to use for sorting customer profiles. For example, -by total money spent with the merchant or the date of their first purchase. - -### Structure - -`CustomerSort` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `field` | [`String (Customer Sort Field)`](/doc/models/customer-sort-field.md) | Optional | Indicates the sort criteria for a list of Customers. | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | - -### Example (as JSON) - -```json -{ - "field": null, - "order": null -} -``` - +## Customer Sort + +Indicates the field to use for sorting customer profiles. For example, +by total money spent with the merchant or the date of their first purchase. + +### Structure + +`CustomerSort` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `field` | [`String (Customer Sort Field)`](/doc/models/customer-sort-field.md) | Optional | Indicates the sort criteria for a list of Customers. | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | + +### Example (as JSON) + +```json +{ + "field": null, + "order": null +} +``` + diff --git a/doc/models/customer.md b/doc/models/customer.md index bb9da21e..2b2da0fd 100644 --- a/doc/models/customer.md +++ b/doc/models/customer.md @@ -1,55 +1,55 @@ -## Customer - -Represents one of a business's customers, which can have one or more -cards on file associated with it. - -### Structure - -`Customer` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | | The customer's unique ID. | -| `created_at` | `String` | | The time when the customer was created, in RFC 3339 format. | -| `updated_at` | `String` | | The time when the customer was last updated, in RFC 3339 format. | -| `cards` | [`Array`](/doc/models/card.md) | Optional | The payment details of the customer's cards on file. | -| `given_name` | `String` | Optional | The customer's given (i.e., first) name. | -| `family_name` | `String` | Optional | The customer's family (i.e., last) name. | -| `nickname` | `String` | Optional | The customer's nickname. | -| `company_name` | `String` | Optional | The name of the customer's company. | -| `email_address` | `String` | Optional | The customer's email address. | -| `address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `phone_number` | `String` | Optional | The customer's phone number. | -| `birthday` | `String` | Optional | The customer's birthday in RFC-3339 format. Year is optional,
timezone and times are not allowed. Example: `0000-09-01T00:00:00-00:00`
for a birthday on September 1st. `1998-09-01T00:00:00-00:00` for a birthday
on September 1st 1998. | -| `reference_id` | `String` | Optional | A second ID you can set to associate the customer with an
entity in another system. | -| `note` | `String` | Optional | A note to associate with the customer. | -| `preferences` | [`Customer Preferences Hash`](/doc/models/customer-preferences.md) | Optional | Represents a particular customer's preferences. | -| `groups` | [`Array`](/doc/models/customer-group-info.md) | Optional | The groups the customer belongs to. | -| `creation_source` | [`String (Customer Creation Source)`](/doc/models/customer-creation-source.md) | Optional | Indicates the method used to create the customer profile. | - -### Example (as JSON) - -```json -{ - "id": "id0", - "created_at": "created_at2", - "updated_at": "updated_at4", - "cards": null, - "given_name": null, - "family_name": null, - "nickname": null, - "company_name": null, - "email_address": null, - "address": null, - "phone_number": null, - "birthday": null, - "reference_id": null, - "note": null, - "preferences": null, - "groups": null, - "creation_source": null -} -``` - +## Customer + +Represents one of a business's customers, which can have one or more +cards on file associated with it. + +### Structure + +`Customer` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | | The customer's unique ID. | +| `created_at` | `String` | | The time when the customer was created, in RFC 3339 format. | +| `updated_at` | `String` | | The time when the customer was last updated, in RFC 3339 format. | +| `cards` | [`Array`](/doc/models/card.md) | Optional | The payment details of the customer's cards on file. | +| `given_name` | `String` | Optional | The customer's given (i.e., first) name. | +| `family_name` | `String` | Optional | The customer's family (i.e., last) name. | +| `nickname` | `String` | Optional | The customer's nickname. | +| `company_name` | `String` | Optional | The name of the customer's company. | +| `email_address` | `String` | Optional | The customer's email address. | +| `address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `phone_number` | `String` | Optional | The customer's phone number. | +| `birthday` | `String` | Optional | The customer's birthday in RFC-3339 format. Year is optional,
timezone and times are not allowed. Example: `0000-09-01T00:00:00-00:00`
for a birthday on September 1st. `1998-09-01T00:00:00-00:00` for a birthday
on September 1st 1998. | +| `reference_id` | `String` | Optional | A second ID you can set to associate the customer with an
entity in another system. | +| `note` | `String` | Optional | A note to associate with the customer. | +| `preferences` | [`Customer Preferences Hash`](/doc/models/customer-preferences.md) | Optional | Represents a particular customer's preferences. | +| `groups` | [`Array`](/doc/models/customer-group-info.md) | Optional | The groups the customer belongs to. | +| `creation_source` | [`String (Customer Creation Source)`](/doc/models/customer-creation-source.md) | Optional | Indicates the method used to create the customer profile. | + +### Example (as JSON) + +```json +{ + "id": "id0", + "created_at": "created_at2", + "updated_at": "updated_at4", + "cards": null, + "given_name": null, + "family_name": null, + "nickname": null, + "company_name": null, + "email_address": null, + "address": null, + "phone_number": null, + "birthday": null, + "reference_id": null, + "note": null, + "preferences": null, + "groups": null, + "creation_source": null +} +``` + diff --git a/doc/models/date-range.md b/doc/models/date-range.md index b17923d3..4795df93 100644 --- a/doc/models/date-range.md +++ b/doc/models/date-range.md @@ -1,25 +1,25 @@ -## Date Range - +## Date Range + A range defined by two dates. Used for filtering a query for Connect v2 -objects that have date properties. - -### Structure - -`DateRange` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `start_date` | `String` | Optional | String in `YYYY-MM-DD` format, e.g. `2017-10-31` per the ISO 8601
extended format for calendar dates.
The beginning of a date range (inclusive) | -| `end_date` | `String` | Optional | String in `YYYY-MM-DD` format, e.g. `2017-10-31` per the ISO 8601
extended format for calendar dates.
The end of a date range (inclusive) | - -### Example (as JSON) - -```json -{ - "start_date": null, - "end_date": null -} -``` - +objects that have date properties. + +### Structure + +`DateRange` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `start_date` | `String` | Optional | String in `YYYY-MM-DD` format, e.g. `2017-10-31` per the ISO 8601
extended format for calendar dates.
The beginning of a date range (inclusive) | +| `end_date` | `String` | Optional | String in `YYYY-MM-DD` format, e.g. `2017-10-31` per the ISO 8601
extended format for calendar dates.
The end of a date range (inclusive) | + +### Example (as JSON) + +```json +{ + "start_date": null, + "end_date": null +} +``` + diff --git a/doc/models/day-of-week.md b/doc/models/day-of-week.md index 9cf700d8..26fcad60 100644 --- a/doc/models/day-of-week.md +++ b/doc/models/day-of-week.md @@ -1,20 +1,20 @@ -## Day of Week - -Indicates the specific day of the week. - -### Enumeration - -`DayOfWeek` - -### Fields - -| Name | Description | -| --- | --- | -| `SUN` | Sunday | -| `MON` | Monday | -| `TUE` | Tuesday | -| `WED` | Wednesday | -| `THU` | Thursday | -| `FRI` | Friday | -| `SAT` | Saturday | - +## Day of Week + +Indicates the specific day of the week. + +### Enumeration + +`DayOfWeek` + +### Fields + +| Name | Description | +| --- | --- | +| `SUN` | Sunday | +| `MON` | Monday | +| `TUE` | Tuesday | +| `WED` | Wednesday | +| `THU` | Thursday | +| `FRI` | Friday | +| `SAT` | Saturday | + diff --git a/doc/models/delete-break-type-response.md b/doc/models/delete-break-type-response.md index c0ae23cc..96d33e28 100644 --- a/doc/models/delete-break-type-response.md +++ b/doc/models/delete-break-type-response.md @@ -1,21 +1,21 @@ -## Delete Break Type Response - -The response to a request to delete a `BreakType`. May contain a set -of `Error` objects if the request resulted in errors. - -### Structure - -`DeleteBreakTypeResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{} -``` - +## Delete Break Type Response + +The response to a request to delete a `BreakType`. May contain a set +of `Error` objects if the request resulted in errors. + +### Structure + +`DeleteBreakTypeResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/delete-catalog-object-response.md b/doc/models/delete-catalog-object-response.md index 001f9a4e..77fd2e10 100644 --- a/doc/models/delete-catalog-object-response.md +++ b/doc/models/delete-catalog-object-response.md @@ -1,26 +1,26 @@ -## Delete Catalog Object Response - -### Structure - -`DeleteCatalogObjectResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `deleted_object_ids` | `Array` | Optional | The IDs of all [CatalogObject](./models/catalog-object.md)s deleted by this request.
Multiple IDs may be returned when associated objects are also deleted, for example
a [CatalogItemVariation](./models/catalog-item-variation.md) will be deleted (and its ID included in this field)
when its parent [CatalogItem](./models/catalog-item.md) is deleted. | -| `deleted_at` | `String` | Optional | The database [timestamp](#workingwithdates) of this deletion in RFC 3339 format, e.g.,
"2016-09-04T23:59:33.123Z". | - -### Example (as JSON) - -```json -{ - "deleted_object_ids": [ - "7SB3ZQYJ5GDMVFL7JK46JCHT", - "KQLFFHA6K6J3YQAQAWDQAL57" - ], - "deleted_at": "2016-11-16T22:25:24.878Z" -} -``` - +## Delete Catalog Object Response + +### Structure + +`DeleteCatalogObjectResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `deleted_object_ids` | `Array` | Optional | The IDs of all [CatalogObject](#type-catalogobject)s deleted by this request.
Multiple IDs may be returned when associated objects are also deleted, for example
a [CatalogItemVariation](#type-catalogitemvariation) will be deleted (and its ID included in this field)
when its parent [CatalogItem](#type-catalogitem) is deleted. | +| `deleted_at` | `String` | Optional | The database [timestamp](#workingwithdates) of this deletion in RFC 3339 format, e.g.,
"2016-09-04T23:59:33.123Z". | + +### Example (as JSON) + +```json +{ + "deleted_object_ids": [ + "7SB3ZQYJ5GDMVFL7JK46JCHT", + "KQLFFHA6K6J3YQAQAWDQAL57" + ], + "deleted_at": "2016-11-16T22:25:24.878Z" +} +``` + diff --git a/doc/models/delete-customer-card-response.md b/doc/models/delete-customer-card-response.md index b2e6e015..4c11f6c7 100644 --- a/doc/models/delete-customer-card-response.md +++ b/doc/models/delete-customer-card-response.md @@ -1,21 +1,21 @@ -## Delete Customer Card Response - -Defines the fields that are included in the response body of -a request to the DeleteCustomerCard endpoint. - -### Structure - -`DeleteCustomerCardResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{} -``` - +## Delete Customer Card Response + +Defines the fields that are included in the response body of +a request to the DeleteCustomerCard endpoint. + +### Structure + +`DeleteCustomerCardResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/delete-customer-response.md b/doc/models/delete-customer-response.md index f75d78ac..675149fd 100644 --- a/doc/models/delete-customer-response.md +++ b/doc/models/delete-customer-response.md @@ -1,21 +1,21 @@ -## Delete Customer Response - -Defines the fields that are included in the response body of -a request to the DeleteCustomer endpoint. - -### Structure - -`DeleteCustomerResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{} -``` - +## Delete Customer Response + +Defines the fields that are included in the response body of +a request to the DeleteCustomer endpoint. + +### Structure + +`DeleteCustomerResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/delete-shift-response.md b/doc/models/delete-shift-response.md index 5d21b767..5edb0965 100644 --- a/doc/models/delete-shift-response.md +++ b/doc/models/delete-shift-response.md @@ -1,21 +1,21 @@ -## Delete Shift Response - -The response to a request to delete a `Shift`. May contain a set of -`Error` objects if the request resulted in errors. - -### Structure - -`DeleteShiftResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{} -``` - +## Delete Shift Response + +The response to a request to delete a `Shift`. May contain a set of +`Error` objects if the request resulted in errors. + +### Structure + +`DeleteShiftResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/device.md b/doc/models/device.md index 2269c77e..5b3f5204 100644 --- a/doc/models/device.md +++ b/doc/models/device.md @@ -1,22 +1,22 @@ -## Device - -### Structure - -`Device` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The device's Square-issued ID. | -| `name` | `String` | Optional | The device's merchant-specified name. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null -} -``` - +## Device + +### Structure + +`Device` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The device's Square-issued ID. | +| `name` | `String` | Optional | The device's merchant-specified name. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null +} +``` + diff --git a/doc/models/employee-status.md b/doc/models/employee-status.md index d2ed39cb..45dc574b 100644 --- a/doc/models/employee-status.md +++ b/doc/models/employee-status.md @@ -1,15 +1,15 @@ -## Employee Status - -The status of the Employee being retrieved. - -### Enumeration - -`EmployeeStatus` - -### Fields - -| Name | Description | -| --- | --- | -| `ACTIVE` | Specifies that the employee is in the Active state. | -| `INACTIVE` | Specifies that the employee is in the Inactive state. | - +## Employee Status + +The status of the Employee being retrieved. + +### Enumeration + +`EmployeeStatus` + +### Fields + +| Name | Description | +| --- | --- | +| `ACTIVE` | Specifies that the employee is in the Active state. | +| `INACTIVE` | Specifies that the employee is in the Inactive state. | + diff --git a/doc/models/employee-wage.md b/doc/models/employee-wage.md index d3263e50..14b5d47f 100644 --- a/doc/models/employee-wage.md +++ b/doc/models/employee-wage.md @@ -1,29 +1,29 @@ -## Employee Wage - -The hourly wage rate that an employee will earn on a `Shift` for doing the job -specified by the `title` property of this object. - -### Structure - -`EmployeeWage` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | UUID for this object. | -| `employee_id` | `String` | | The `Employee` that this wage is assigned to. | -| `title` | `String` | Optional | The job title that this wage relates to. | -| `hourly_rate` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "id": null, - "employee_id": "employee_id0", - "title": null, - "hourly_rate": null -} -``` - +## Employee Wage + +The hourly wage rate that an employee will earn on a `Shift` for doing the job +specified by the `title` property of this object. + +### Structure + +`EmployeeWage` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | UUID for this object. | +| `employee_id` | `String` | | The `Employee` that this wage is assigned to. | +| `title` | `String` | Optional | The job title that this wage relates to. | +| `hourly_rate` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "id": null, + "employee_id": "employee_id0", + "title": null, + "hourly_rate": null +} +``` + diff --git a/doc/models/employee.md b/doc/models/employee.md index 24521ee4..ef0ab927 100644 --- a/doc/models/employee.md +++ b/doc/models/employee.md @@ -1,39 +1,39 @@ -## Employee - -An employee created in the **Square Dashboard** account of a business. -Used by the Labor API. - -### Structure - -`Employee` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | UUID for this `Employee`. | -| `first_name` | `String` | Optional | Given (first) name of the employee. | -| `last_name` | `String` | Optional | Family (last) name of the employee | -| `email` | `String` | Optional | Email of the employee | -| `phone_number` | `String` | Optional | Phone number of the employee in E.164 format, i.e. "+12125554250" | -| `location_ids` | `Array` | Optional | A list of location IDs where this employee has access. | -| `status` | [`String (Employee Status)`](/doc/models/employee-status.md) | Optional | The status of the Employee being retrieved. | -| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format. | -| `updated_at` | `String` | Optional | A read-only timestamp in RFC 3339 format. | - -### Example (as JSON) - -```json -{ - "id": null, - "first_name": null, - "last_name": null, - "email": null, - "phone_number": null, - "location_ids": null, - "status": null, - "created_at": null, - "updated_at": null -} -``` - +## Employee + +An employee created in the **Square Dashboard** account of a business. +Used by the Labor API. + +### Structure + +`Employee` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | UUID for this `Employee`. | +| `first_name` | `String` | Optional | Given (first) name of the employee. | +| `last_name` | `String` | Optional | Family (last) name of the employee | +| `email` | `String` | Optional | Email of the employee | +| `phone_number` | `String` | Optional | Phone number of the employee in E.164 format, i.e. "+12125554250" | +| `location_ids` | `Array` | Optional | A list of location IDs where this employee has access. | +| `status` | [`String (Employee Status)`](/doc/models/employee-status.md) | Optional | The status of the Employee being retrieved. | +| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format. | +| `updated_at` | `String` | Optional | A read-only timestamp in RFC 3339 format. | + +### Example (as JSON) + +```json +{ + "id": null, + "first_name": null, + "last_name": null, + "email": null, + "phone_number": null, + "location_ids": null, + "status": null, + "created_at": null, + "updated_at": null +} +``` + diff --git a/doc/models/error-category.md b/doc/models/error-category.md index 8c29f121..3445bd39 100644 --- a/doc/models/error-category.md +++ b/doc/models/error-category.md @@ -1,20 +1,20 @@ -## Error Category - +## Error Category + Indicates which high-level category of error has occurred during a -request to the Connect API. - -### Enumeration - -`ErrorCategory` - -### Fields - -| Name | Description | -| --- | --- | -| `API_ERROR` | An error occurred with the Connect API itself. | -| `AUTHENTICATION_ERROR` | An authentication error occurred. Most commonly, the request had
a missing, malformed, or otherwise invalid `Authorization` header. | -| `INVALID_REQUEST_ERROR` | The request was invalid. Most commonly, a required parameter was
missing, or a provided parameter had an invalid value. | -| `RATE_LIMIT_ERROR` | Your application reached the Connect API rate limit. Retry your request
after a while. | -| `PAYMENT_METHOD_ERROR` | An error occurred while processing a payment method. Most commonly,
the details of the payment method were invalid (such as a card's CVV
or expiration date). | -| `REFUND_ERROR` | An error occurred while attempting to process a refund. | - +request to the Connect API. + +### Enumeration + +`ErrorCategory` + +### Fields + +| Name | Description | +| --- | --- | +| `API_ERROR` | An error occurred with the Connect API itself. | +| `AUTHENTICATION_ERROR` | An authentication error occurred. Most commonly, the request had
a missing, malformed, or otherwise invalid `Authorization` header. | +| `INVALID_REQUEST_ERROR` | The request was invalid. Most commonly, a required parameter was
missing, or a provided parameter had an invalid value. | +| `RATE_LIMIT_ERROR` | Your application reached the Connect API rate limit. Retry your
request after a while. | +| `PAYMENT_METHOD_ERROR` | An error occurred while processing a payment method. Most commonly,
the details of the payment method were invalid (such as a card's CVV
or expiration date). | +| `REFUND_ERROR` | An error occurred while attempting to process a refund. | + diff --git a/doc/models/error-code.md b/doc/models/error-code.md index 2e048622..cd7941b0 100644 --- a/doc/models/error-code.md +++ b/doc/models/error-code.md @@ -1,106 +1,132 @@ -## Error Code - -Indicates specific errors that can occur during a request to the -Connect API. - -### Enumeration - -`ErrorCode` - -### Fields - -| Name | Description | -| --- | --- | -| `INTERNAL_SERVER_ERROR` | - | -| `UNAUTHORIZED` | - | -| `ACCESS_TOKEN_EXPIRED` | - | -| `ACCESS_TOKEN_REVOKED` | - | -| `FORBIDDEN` | - | -| `INSUFFICIENT_SCOPES` | - | -| `APPLICATION_DISABLED` | - | -| `V1_APPLICATION` | - | -| `V1_ACCESS_TOKEN` | - | -| `CARD_PROCESSING_NOT_ENABLED` | - | -| `BAD_REQUEST` | - | -| `MISSING_REQUIRED_PARAMETER` | - | -| `INCORRECT_TYPE` | - | -| `INVALID_TIME` | - | -| `INVALID_TIME_RANGE` | - | -| `INVALID_VALUE` | - | -| `INVALID_CURSOR` | - | -| `UNKNOWN_QUERY_PARAMETER` | - | -| `CONFLICTING_PARAMETERS` | - | -| `EXPECTED_JSON_BODY` | - | -| `INVALID_SORT_ORDER` | - | -| `VALUE_REGEX_MISMATCH` | - | -| `VALUE_TOO_SHORT` | - | -| `VALUE_TOO_LONG` | - | -| `VALUE_TOO_LOW` | - | -| `VALUE_TOO_HIGH` | - | -| `VALUE_EMPTY` | - | -| `ARRAY_LENGTH_TOO_LONG` | - | -| `ARRAY_LENGTH_TOO_SHORT` | - | -| `ARRAY_EMPTY` | - | -| `EXPECTED_BOOLEAN` | - | -| `EXPECTED_INTEGER` | - | -| `EXPECTED_FLOAT` | - | -| `EXPECTED_STRING` | - | -| `EXPECTED_OBJECT` | - | -| `EXPECTED_ARRAY` | - | -| `EXPECTED_MAP` | - | -| `EXPECTED_BASE64_ENCODED_BYTE_ARRAY` | - | -| `INVALID_ARRAY_VALUE` | - | -| `INVALID_ENUM_VALUE` | - | -| `INVALID_CONTENT_TYPE` | - | -| `INVALID_FORM_VALUE` | - | -| `ONE_INSTRUMENT_EXPECTED` | - | -| `NO_FIELDS_SET` | - | -| `DEPRECATED_FIELD_SET` | - | -| `RETIRED_FIELD_SET` | - | -| `CARD_EXPIRED` | - | -| `INVALID_EXPIRATION` | - | -| `INVALID_EXPIRATION_YEAR` | - | -| `INVALID_EXPIRATION_DATE` | - | -| `UNSUPPORTED_CARD_BRAND` | - | -| `UNSUPPORTED_ENTRY_METHOD` | - | -| `INVALID_ENCRYPTED_CARD` | - | -| `INVALID_CARD` | - | -| `DELAYED_TRANSACTION_EXPIRED` | - | -| `DELAYED_TRANSACTION_CANCELED` | - | -| `DELAYED_TRANSACTION_CAPTURED` | - | -| `DELAYED_TRANSACTION_FAILED` | - | -| `CARD_TOKEN_EXPIRED` | - | -| `CARD_TOKEN_USED` | - | -| `AMOUNT_TOO_HIGH` | - | -| `UNSUPPORTED_INSTRUMENT_TYPE` | - | -| `REFUND_AMOUNT_INVALID` | - | -| `REFUND_ALREADY_PENDING` | - | -| `PAYMENT_NOT_REFUNDABLE` | - | -| `INVALID_CARD_DATA` | - | -| `LOCATION_MISMATCH` | - | -| `IDEMPOTENCY_KEY_REUSED` | - | -| `UNEXPECTED_VALUE` | - | -| `SANDBOX_NOT_SUPPORTED` | - | -| `INVALID_EMAIL_ADDRESS` | - | -| `INVALID_PHONE_NUMBER` | - | -| `CHECKOUT_EXPIRED` | - | -| `BAD_CERTIFICATE` | - | -| `INVALID_SQUARE_VERSION_FORMAT` | - | -| `API_VERSION_INCOMPATIBLE` | - | -| `CARD_DECLINED` | - | -| `VERIFY_CVV_FAILURE` | - | -| `VERIFY_AVS_FAILURE` | - | -| `CARD_DECLINED_CALL_ISSUER` | - | -| `NOT_FOUND` | - | -| `APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND` | - | -| `METHOD_NOT_ALLOWED` | - | -| `NOT_ACCEPTABLE` | - | -| `REQUEST_TIMEOUT` | - | -| `CONFLICT` | - | -| `REQUEST_ENTITY_TOO_LARGE` | - | -| `UNSUPPORTED_MEDIA_TYPE` | - | -| `RATE_LIMITED` | - | -| `NOT_IMPLEMENTED` | - | -| `SERVICE_UNAVAILABLE` | - | -| `GATEWAY_TIMEOUT` | - | - +## Error Code + +Indicates the specific error that occurred during a request to a +Square API. + +### Enumeration + +`ErrorCode` + +### Fields + +| Name | Description | +| --- | --- | +| `INTERNAL_SERVER_ERROR` | 500 Internal Server Error - a general server error occurred. | +| `UNAUTHORIZED` | 401 Unauthorized - a general authorization error occurred. | +| `ACCESS_TOKEN_EXPIRED` | 401 Unauthorized - the provided access token has expired. | +| `ACCESS_TOKEN_REVOKED` | 401 Unauthorized - the provided access token has been revoked. | +| `FORBIDDEN` | 403 Forbidden - a general access error occurred. | +| `INSUFFICIENT_SCOPES` | 403 Forbidden - the provided access token does not have permission
to execute the requested action. | +| `APPLICATION_DISABLED` | 403 Forbidden - the calling application was disabled. | +| `V1_APPLICATION` | 403 Forbidden - the calling application was created prior to
2016-03-30 and is not compatible with v2 Square API calls. | +| `V1_ACCESS_TOKEN` | 403 Forbidden - the calling application is using an access token
created prior to 2016-03-30 and is not compatible with v2 Square API
calls. | +| `CARD_PROCESSING_NOT_ENABLED` | 403 Forbidden - the location provided in the API call is not
enabled for credit card processing. | +| `BAD_REQUEST` | 400 Bad Request - a general error occurred. | +| `MISSING_REQUIRED_PARAMETER` | 400 Bad Request - the request is missing a required path, query, or
body parameter. | +| `INCORRECT_TYPE` | 400 Bad Request - the value provided in the request is the wrong
type. For example, a string instead of an integer. | +| `INVALID_TIME` | 400 Bad Request - formatting for the provided time value is
incorrect. | +| `INVALID_TIME_RANGE` | 400 Bad Request - the time range provided in the request is invalid.
For example, the end time is before the start time. | +| `INVALID_VALUE` | 400 Bad Request - the provided value is invalid. For example,
including `%` in a phone number. | +| `INVALID_CURSOR` | 400 Bad Request - the pagination cursor included in the request is
invalid. | +| `UNKNOWN_QUERY_PARAMETER` | 400 Bad Request - the query parameters provided is invalid for the
requested endpoint. | +| `CONFLICTING_PARAMETERS` | 400 Bad Request - 1 or more of the request parameters conflict with
each other. | +| `EXPECTED_JSON_BODY` | 400 Bad Request - the request body is not a JSON object. | +| `INVALID_SORT_ORDER` | 400 Bad Request - the provided sort order is not a valid key.
Currently, sort order must be `ASC` or `DESC`. | +| `VALUE_REGEX_MISMATCH` | 400 Bad Request - the provided value does not match an expected
regular expression. | +| `VALUE_TOO_SHORT` | 400 Bad Request - the provided string value is shorter than the
minimum length allowed. | +| `VALUE_TOO_LONG` | 400 Bad Request - the provided string value is longer than the
maximum length allowed. | +| `VALUE_TOO_LOW` | 400 Bad Request - the provided value is less than the supported
minimum. | +| `VALUE_TOO_HIGH` | 400 Bad Request - the provided value is greater than the supported
maximum. | +| `VALUE_EMPTY` | 400 Bad Request - the provided value has a default (empty) value
such as a blank string. | +| `ARRAY_LENGTH_TOO_LONG` | 400 Bad Request - the provided array has too many elements. | +| `ARRAY_LENGTH_TOO_SHORT` | 400 Bad Request - the provided array has too few elements. | +| `ARRAY_EMPTY` | 400 Bad Request - the provided array is empty. | +| `EXPECTED_BOOLEAN` | 400 Bad Request - the endpoint expected the provided value to be a
boolean. | +| `EXPECTED_INTEGER` | 400 Bad Request - the endpoint expected the provided value to be an
integer. | +| `EXPECTED_FLOAT` | 400 Bad Request - the endpoint expected the provided value to be a
float. | +| `EXPECTED_STRING` | 400 Bad Request - the endpoint expected the provided value to be a
string. | +| `EXPECTED_OBJECT` | 400 Bad Request - the endpoint expected the provided value to be a
JSON object. | +| `EXPECTED_ARRAY` | 400 Bad Request - the endpoint expected the provided value to be an
array or list. | +| `EXPECTED_MAP` | 400 Bad Request - the endpoint expected the provided value to be a
map or associative array. | +| `EXPECTED_BASE64_ENCODED_BYTE_ARRAY` | 400 Bad Request - the endpoint expected the provided value to be an
array encoded in base64. | +| `INVALID_ARRAY_VALUE` | 400 Bad Request - 1 or more object in the array does not match the
array type. | +| `INVALID_ENUM_VALUE` | 400 Bad Request - the provided static string is not valid for the
field. | +| `INVALID_CONTENT_TYPE` | 400 Bad Request - invalid content type header. | +| `INVALID_FORM_VALUE` | 400 Bad Request - Only relevant for applications created prior to
2016-03-30. Indicates there was an error while parsing form values. | +| `ONE_INSTRUMENT_EXPECTED` | 400 Bad Request - a general error occurred. | +| `NO_FIELDS_SET` | 400 Bad Request - a general error occurred. | +| `CARD_EXPIRED` | The card issuer declined the request because the card is expired. | +| `INVALID_EXPIRATION` | The expiration date for the payment card is invalid. For example,
it indicates a date in the past. | +| `INVALID_EXPIRATION_YEAR` | The expiration year for the payment card is invalid. For example,
it indicates a year in the past or contains invalid characters. | +| `INVALID_EXPIRATION_DATE` | The expiration date for the payment card is invalid. For example,
it contains invalid characters. | +| `UNSUPPORTED_CARD_BRAND` | The credit card provided is not from a supported issuer. | +| `UNSUPPORTED_ENTRY_METHOD` | The entry method for the credit card (swipe, dip, tap) is not supported. | +| `INVALID_ENCRYPTED_CARD` | The encrypted card information is invalid. | +| `INVALID_CARD` | The credit card cannot be validated based on the provided details. | +| `GENERIC_DECLINE` | The credit card was decline by the issuer for an unspecified
reason. | +| `CVV_FAILURE` | The card issuer declined the request because the CVV value is invalid. | +| `ADDRESS_VERIFICATION_FAILURE` | The card issuer declined the request because the postal code is invalid. | +| `INVALID_ACCOUNT` | The card issuer was not able to locate account on record. | +| `CURRENCY_MISMATCH` | The currency associated with the payment is not valid for the provided
funding source. For example, a gift card funded in USD cannot be used to process
payments in GBP. | +| `INSUFFICIENT_FUNDS` | The funding source has insufficient funds to cover the payment. | +| `INSUFFICIENT_PERMISSIONS` | The Square account associated with the payment does not have
the permissions necessary to accept the payment. For example, Square may
limit which merchants are allowed to process gift card payments. | +| `CARDHOLDER_INSUFFICIENT_PERMISSIONS` | The funding source associated with the payment has limitations on
how it can be used. For example, it is only valid for specific merchants
or transaction types. | +| `INVALID_LOCATION` | The associated Square account is not allowed to take payments in this region. | +| `TRANSACTION_LIMIT` | The payment amount violates an associated transaction limit, i.e.,
it is too low or too high. For example, the card used is a prepaid credit
card. | +| `VOICE_FAILURE` | The transaction was declined because the card issuer requires voice
authorization from the cardholder. | +| `PAN_FAILURE` | The specified card number is invalid. For example, it is of
incorrect length or is incorrectly formatted. | +| `EXPIRATION_FAILURE` | The card expiration date is either invalid or indicates that the
card is expired. | +| `CARD_NOT_SUPPORTED` | The card is not supported in the geographic region associated with
the Square account. For example, the card is accepted in the US but not in
Japan. | +| `INVALID_PIN` | The card issuer declined the request because the PIN is invalid. | +| `INVALID_POSTAL_CODE` | The postal code is improperly formatted. | +| `INVALID_FEES` | The total fee amount associated with the payment is too high. | +| `MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED` | The payment was declined because manually keying-in the card
information is disallowed. The card must be swiped, tapped, or dipped. | +| `PAYMENT_LIMIT_EXCEEDED` | Square declined the request because the payment amount exceeds the
processing limit for the associated Square account. | +| `GIFT_CARD_AVAILABLE_AMOUNT` | Square declined the request because the payment amount exceeds the
processing limit for the associated Square account. | +| `DELAYED_TRANSACTION_EXPIRED` | The application tried to update a delayed-capture payment that has expired. | +| `DELAYED_TRANSACTION_CANCELED` | The application tried to cancel a delayed-capture payment that was already cancelled. | +| `DELAYED_TRANSACTION_CAPTURED` | The application tried to capture a delayed-capture payment that was already captured. | +| `DELAYED_TRANSACTION_FAILED` | The application tried to update a delayed-capture payment that failed. | +| `CARD_TOKEN_EXPIRED` | The provided card token (nonce) has expired. | +| `CARD_TOKEN_USED` | The provided card token (nonce) was already used to process payment. | +| `AMOUNT_TOO_HIGH` | The requested payment amount is too high for the provided payment source. | +| `UNSUPPORTED_INSTRUMENT_TYPE` | The API request references an unsupported instrument type/ | +| `REFUND_AMOUNT_INVALID` | The requested refund amount exceeds the amount available to refund. | +| `REFUND_ALREADY_PENDING` | The payment already has a pending refund. | +| `PAYMENT_NOT_REFUNDABLE` | The payment is not refundable. For example, a previous refund has
already been rejected and no new refunds can be accepted. | +| `INVALID_CARD_DATA` | Generic error - the provided card data is invalid. | +| `LOCATION_MISMATCH` | Generic error - the given location does not matching what is expected. | +| `IDEMPOTENCY_KEY_REUSED` | The provided idempotency key has already been used. | +| `UNEXPECTED_VALUE` | General error - the value provided was unexpected. | +| `SANDBOX_NOT_SUPPORTED` | The API request is not supported in sandbox. | +| `INVALID_EMAIL_ADDRESS` | The provided email address is invalid. | +| `INVALID_PHONE_NUMBER` | The provided phone number is invalid. | +| `CHECKOUT_EXPIRED` | The provided checkout URL has expired. | +| `BAD_CERTIFICATE` | Bad certificate. | +| `INVALID_SQUARE_VERSION_FORMAT` | The provided Square-Version is incorrectly formatted. | +| `API_VERSION_INCOMPATIBLE` | The provided Square-Version is incompatibile with the requested action. | +| `INVALID_URL` | The provided API URL is invalid. | +| `HTTPS_ONLY` | HTTPS only. | +| `CARD_DECLINED` | 402 Request failed - the card was declined. | +| `VERIFY_CVV_FAILURE` | 402 Request failed - the CVV could not be verified. | +| `VERIFY_AVS_FAILURE` | 402 Request failed - the AVS could not be verified. | +| `CARD_DECLINED_CALL_ISSUER` | 402 Request failed - the payment card was declined with a request
for the card holder to call the issuer. | +| `CARD_DECLINED_VERIFICATION_REQUIRED` | 402 Request failed - the payment card was declined with a request
for additional verification. | +| `BAD_EXPIRATION` | 402 Request failed - the card expiration date is either missing or
incorrectly formatted. | +| `CHIP_INSERTION_REQUIRED` | 402 Request failed - the card issuer requires that the card be read
using a chip reader. | +| `ALLOWABLE_PIN_TRIES_EXCEEDED` | 402 Request failed - the card has exhausted its available pin entry
retries set by the card issuer. Resolving the error typically requires the
card holder to contact the card issuer. | +| `RESERVATION_DECLINED` | 402 Request failed - The card issuer declined the refund. | +| `NOT_FOUND` | 404 Not Found - a general error occurred. | +| `APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND` | 404 Not Found - Square could not find the associated Apple Pay certificate. | +| `METHOD_NOT_ALLOWED` | 405 Method Not Allowed - a general error occurred. | +| `NOT_ACCEPTABLE` | 406 Not Acceptable - a general error occurred. | +| `REQUEST_TIMEOUT` | 408 Request Timeout - a general error occurred. | +| `CONFLICT` | 409 Conflict - a general error occurred. | +| `REQUEST_ENTITY_TOO_LARGE` | 413 Request Entity Too Large - a general error occurred. | +| `UNSUPPORTED_MEDIA_TYPE` | 415 Unsupported Media Type - a general error occurred. | +| `RATE_LIMITED` | 429 Rate Limited - a general error occurred. | +| `NOT_IMPLEMENTED` | 501 Not Implemented - a general error occurred. | +| `SERVICE_UNAVAILABLE` | 503 Service Unavailable - a general error occurred. | +| `TEMPORARY_ERROR` | A temporary internal error occurred. You can safely retry your call
using the same idempotency key. | +| `GATEWAY_TIMEOUT` | 504 Gateway Timeout - a general error occurred. | + diff --git a/doc/models/error.md b/doc/models/error.md index f4b63b47..b66b6f96 100644 --- a/doc/models/error.md +++ b/doc/models/error.md @@ -1,28 +1,28 @@ -## Error - -Represents an error encountered during a request to the Connect API. - -### Structure - -`Error` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `category` | [`String (Error Category)`](/doc/models/error-category.md) | | Indicates which high-level category of error has occurred during a
request to the Connect API. | -| `code` | [`String (Error Code)`](/doc/models/error-code.md) | | Indicates specific errors that can occur during a request to the
Connect API. | -| `detail` | `String` | Optional | A human-readable description of the error for debugging purposes. | -| `field` | `String` | Optional | The name of the field provided in the original request that the error
pertains to, if any. | - -### Example (as JSON) - -```json -{ - "category": "INVALID_REQUEST_ERROR", - "code": "ACCESS_TOKEN_EXPIRED", - "detail": null, - "field": null -} -``` - +## Error + +Represents an error encountered during a request to the Connect API. + +### Structure + +`Error` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `category` | [`String (Error Category)`](/doc/models/error-category.md) | | Indicates which high-level category of error has occurred during a
request to the Connect API. | +| `code` | [`String (Error Code)`](/doc/models/error-code.md) | | Indicates the specific error that occurred during a request to a
Square API. | +| `detail` | `String` | Optional | A human-readable description of the error for debugging purposes. | +| `field` | `String` | Optional | The name of the field provided in the original request (if any) that
the error pertains to. | + +### Example (as JSON) + +```json +{ + "category": "INVALID_REQUEST_ERROR", + "code": "INVALID_PIN", + "detail": null, + "field": null +} +``` + diff --git a/doc/models/get-break-type-response.md b/doc/models/get-break-type-response.md index fcb79c57..66009736 100644 --- a/doc/models/get-break-type-response.md +++ b/doc/models/get-break-type-response.md @@ -1,34 +1,34 @@ -## Get Break Type Response - -The response to a request to get a `BreakType`. Contains -the requested `BreakType` objects. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`GetBreakTypeResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `break_type` | [`Break Type Hash`](/doc/models/break-type.md) | Optional | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "break_type": { - "id": "lA0mj_RSOprNPwMUXdYp", - "location_id": "059SB0E0WCNWS", - "break_name": "Lunch Break", - "expected_duration": "PT30M", - "is_paid": true, - "version": 1, - "created_at": "2019-02-21T17:50:00Z", - "updated_at": "2019-02-21T17:50:00Z" - } -} -``` - +## Get Break Type Response + +The response to a request to get a `BreakType`. Contains +the requested `BreakType` objects. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`GetBreakTypeResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `break_type` | [`Break Type Hash`](/doc/models/break-type.md) | Optional | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "break_type": { + "id": "lA0mj_RSOprNPwMUXdYp", + "location_id": "059SB0E0WCNWS", + "break_name": "Lunch Break", + "expected_duration": "PT30M", + "is_paid": true, + "version": 1, + "created_at": "2019-02-21T17:50:00Z", + "updated_at": "2019-02-21T17:50:00Z" + } +} +``` + diff --git a/doc/models/get-employee-wage-response.md b/doc/models/get-employee-wage-response.md index 2243c8bb..e4ea5903 100644 --- a/doc/models/get-employee-wage-response.md +++ b/doc/models/get-employee-wage-response.md @@ -1,33 +1,33 @@ -## Get Employee Wage Response - -A response to a request to get an `EmployeeWage`. Contains -the requested `EmployeeWage` objects. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`GetEmployeeWageResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `employee_wage` | [`Employee Wage Hash`](/doc/models/employee-wage.md) | Optional | The hourly wage rate that an employee will earn on a `Shift` for doing the job
specified by the `title` property of this object. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "employee_wage": { - "id": "pXS3qCv7BERPnEGedM4S8mhm", - "employee_id": "33fJchumvVdJwxV0H6L9", - "title": "Manager", - "hourly_rate": { - "amount": 2000, - "currency": "USD" - } - } -} -``` - +## Get Employee Wage Response + +A response to a request to get an `EmployeeWage`. Contains +the requested `EmployeeWage` objects. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`GetEmployeeWageResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `employee_wage` | [`Employee Wage Hash`](/doc/models/employee-wage.md) | Optional | The hourly wage rate that an employee will earn on a `Shift` for doing the job
specified by the `title` property of this object. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "employee_wage": { + "id": "pXS3qCv7BERPnEGedM4S8mhm", + "employee_id": "33fJchumvVdJwxV0H6L9", + "title": "Manager", + "hourly_rate": { + "amount": 2000, + "currency": "USD" + } + } +} +``` + diff --git a/doc/models/get-payment-refund-response.md b/doc/models/get-payment-refund-response.md index 761d6706..316e5c47 100644 --- a/doc/models/get-payment-refund-response.md +++ b/doc/models/get-payment-refund-response.md @@ -1,49 +1,49 @@ -## Get Payment Refund Response - -Defines the fields that are included in the response body of -a request to the [GetRefund](/doc/refunds.md#getpaymentrefund) endpoint. - -Note: if there are errors processing the request, the refund field may not be -present, or it may be present in a FAILED state. - -### Structure - -`GetPaymentRefundResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `refund` | [`Payment Refund Hash`](/doc/models/payment-refund.md) | Optional | Represents a refund of a payment made using Square. Contains information on
the original payment and the amount of money refunded. | - -### Example (as JSON) - -```json -{ - "refund": { - "id": "O2QAAhTYs7rUfzlxT38GMO7LvaB_q7JwCHtxmgXrh8fAhV468WQ44VxDtL7CU4yVRlsbXmI", - "created_at": "2019-07-06T18:01:22.123Z", - "updated_at": "2019-07-06T18:06:03.874Z", - "status": "COMPLETED", - "amount_money": { - "amount": 1000, - "currency": "USD" - }, - "payment_id": "O2QAAhTYs7rUfzlxT38GMO7LvaB", - "order_id": "2duiyoqbfeXY0DBi15GEyk5Epa4F", - "location_id": "XK3DBG77NJBFX", - "processing_fee": [ - { - "effective_at": "2019-07-06T20:01:12.000Z", - "type": "INITIAL", - "amount_money": { - "amount": -59, - "currency": "USD" - } - } - ] - } -} -``` - +## Get Payment Refund Response + +Defines the fields that are included in the response body of +a request to the [GetRefund](#endpoint-refunds-getpaymentrefund) endpoint. + +Note: if there are errors processing the request, the refund field may not be +present, or it may be present in a FAILED state. + +### Structure + +`GetPaymentRefundResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `refund` | [`Payment Refund Hash`](/doc/models/payment-refund.md) | Optional | Represents a refund of a payment made using Square. Contains information on
the original payment and the amount of money refunded. | + +### Example (as JSON) + +```json +{ + "refund": { + "id": "O2QAAhTYs7rUfzlxT38GMO7LvaB_q7JwCHtxmgXrh8fAhV468WQ44VxDtL7CU4yVRlsbXmI", + "created_at": "2019-07-06T18:01:22.123Z", + "updated_at": "2019-07-06T18:06:03.874Z", + "status": "COMPLETED", + "amount_money": { + "amount": 1000, + "currency": "USD" + }, + "payment_id": "O2QAAhTYs7rUfzlxT38GMO7LvaB", + "order_id": "2duiyoqbfeXY0DBi15GEyk5Epa4F", + "location_id": "XK3DBG77NJBFX", + "processing_fee": [ + { + "effective_at": "2019-07-06T20:01:12.000Z", + "type": "INITIAL", + "amount_money": { + "amount": -59, + "currency": "USD" + } + } + ] + } +} +``` + diff --git a/doc/models/get-payment-response.md b/doc/models/get-payment-response.md index 0b7c23b2..06873982 100644 --- a/doc/models/get-payment-response.md +++ b/doc/models/get-payment-response.md @@ -1,71 +1,71 @@ -## Get Payment Response - -Defines the fields that are included in the response body of -a request to the [GetPayment](/doc/payments.md#getpayment) endpoint. - -### Structure - -`GetPaymentResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `payment` | [`Payment Hash`](/doc/models/payment.md) | Optional | Represents a payment processed by the Square API. | - -### Example (as JSON) - -```json -{ - "payment": { - "id": "iqrBxAil6rmDtr7cak9g9WO8uaB", - "created_at": "2019-07-10T13:23:49.154Z", - "updated_at": "2019-07-10T13:23:49.446Z", - "amount_money": { - "amount": 200, - "currency": "USD" - }, - "app_fee_money": { - "amount": 10, - "currency": "USD" - }, - "total_money": { - "amount": 200, - "currency": "USD" - }, - "status": "COMPLETED", - "source_type": "CARD", - "card_details": { - "status": "CAPTURED", - "card": { - "card_brand": "VISA", - "last_4": "2796", - "exp_month": 7, - "exp_year": 2026, - "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw" - }, - "entry_method": "ON_FILE", - "cvv_status": "CVV_ACCEPTED", - "avs_status": "AVS_ACCEPTED", - "auth_result_code": "nsAyY2" - }, - "location_id": "XK3DBG77NJBFX", - "order_id": "qHkNOb03hMgEgoP3gyzFBDY3cg4F", - "reference_id": "123456", - "note": "Brief description", - "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8", - "processing_fee": [ - { - "effective_at": "2019-07-10T15:23:49.000Z", - "type": "INITIAL", - "amount_money": { - "amount": 36, - "currency": "USD" - } - } - ] - } -} -``` - +## Get Payment Response + +Defines the fields that are included in the response body of +a request to the [GetPayment](#endpoint-payments-getpayment) endpoint. + +### Structure + +`GetPaymentResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `payment` | [`Payment Hash`](/doc/models/payment.md) | Optional | Represents a payment processed by the Square API. | + +### Example (as JSON) + +```json +{ + "payment": { + "id": "iqrBxAil6rmDtr7cak9g9WO8uaB", + "created_at": "2019-07-10T13:23:49.154Z", + "updated_at": "2019-07-10T13:23:49.446Z", + "amount_money": { + "amount": 200, + "currency": "USD" + }, + "app_fee_money": { + "amount": 10, + "currency": "USD" + }, + "total_money": { + "amount": 200, + "currency": "USD" + }, + "status": "COMPLETED", + "source_type": "CARD", + "card_details": { + "status": "CAPTURED", + "card": { + "card_brand": "VISA", + "last_4": "2796", + "exp_month": 7, + "exp_year": 2026, + "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw" + }, + "entry_method": "ON_FILE", + "cvv_status": "CVV_ACCEPTED", + "avs_status": "AVS_ACCEPTED", + "auth_result_code": "nsAyY2" + }, + "location_id": "XK3DBG77NJBFX", + "order_id": "qHkNOb03hMgEgoP3gyzFBDY3cg4F", + "reference_id": "123456", + "note": "Brief description", + "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8", + "processing_fee": [ + { + "effective_at": "2019-07-10T15:23:49.000Z", + "type": "INITIAL", + "amount_money": { + "amount": 36, + "currency": "USD" + } + } + ] + } +} +``` + diff --git a/doc/models/get-shift-response.md b/doc/models/get-shift-response.md index ced512e2..3e0c14ad 100644 --- a/doc/models/get-shift-response.md +++ b/doc/models/get-shift-response.md @@ -1,54 +1,54 @@ -## Get Shift Response - -A response to request to get a `Shift`. Contains -the requested `Shift` object. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`GetShiftResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `shift` | [`Shift Hash`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "shift": { - "id": "T35HMQSN89SV4", - "employee_id": "D71KRMQof6cXGUW0aAv7", - "location_id": "PAA1RJZZKXBFG", - "timezone": "America/New_York", - "start_at": "2019-02-23T18:00:00-05:00", - "end_at": "2019-02-23T21:00:00-05:00", - "wage": { - "title": "Cashier", - "hourly_rate": { - "amount": 1457, - "currency": "USD" - } - }, - "breaks": [ - { - "id": "M9BBKEPQAQD2T", - "start_at": "2019-02-23T19:00:00-05:00", - "end_at": "2019-02-23T20:00:00-05:00", - "break_type_id": "92EPDRQKJ5088", - "name": "Lunch Break", - "expected_duration": "PT1H", - "is_paid": true - } - ], - "status": "CLOSED", - "version": 1, - "created_at": "2019-02-27T00:12:12Z", - "updated_at": "2019-02-27T00:12:12Z" - } -} -``` - +## Get Shift Response + +A response to request to get a `Shift`. Contains +the requested `Shift` object. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`GetShiftResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `shift` | [`Shift Hash`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "shift": { + "id": "T35HMQSN89SV4", + "employee_id": "D71KRMQof6cXGUW0aAv7", + "location_id": "PAA1RJZZKXBFG", + "timezone": "America/New_York", + "start_at": "2019-02-23T18:00:00-05:00", + "end_at": "2019-02-23T21:00:00-05:00", + "wage": { + "title": "Cashier", + "hourly_rate": { + "amount": 1457, + "currency": "USD" + } + }, + "breaks": [ + { + "id": "M9BBKEPQAQD2T", + "start_at": "2019-02-23T19:00:00-05:00", + "end_at": "2019-02-23T20:00:00-05:00", + "break_type_id": "92EPDRQKJ5088", + "name": "Lunch Break", + "expected_duration": "PT1H", + "is_paid": true + } + ], + "status": "CLOSED", + "version": 1, + "created_at": "2019-02-27T00:12:12Z", + "updated_at": "2019-02-27T00:12:12Z" + } +} +``` + diff --git a/doc/models/inventory-adjustment.md b/doc/models/inventory-adjustment.md index 4d67c27e..086ac7fd 100644 --- a/doc/models/inventory-adjustment.md +++ b/doc/models/inventory-adjustment.md @@ -1,55 +1,55 @@ -## Inventory Adjustment - -Represents a change in state or quantity of product inventory at a -particular time and location. - -### Structure - -`InventoryAdjustment` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | A unique ID generated by Square for the
[InventoryAdjustment](./models/inventory-adjustment.md). | -| `reference_id` | `String` | Optional | An optional ID provided by the application to tie the
[InventoryAdjustment](./models/inventory-adjustment.md) to an external
system. | -| `from_state` | [`String (Inventory State)`](/doc/models/inventory-state.md) | Optional | Indicates the state of a tracked item quantity in the lifecycle of goods. | -| `to_state` | [`String (Inventory State)`](/doc/models/inventory-state.md) | Optional | Indicates the state of a tracked item quantity in the lifecycle of goods. | -| `location_id` | `String` | Optional | The Square ID of the [Location](./models/location.md) where the related
quantity of items are being tracked. | -| `catalog_object_id` | `String` | Optional | The Square generated ID of the
[CatalogObject](./models/catalog-object.md) being tracked. | -| `catalog_object_type` | `String` | Optional | The [CatalogObjectType](./models/catalog-object-type.md) of the
[CatalogObject](./models/catalog-object.md) being tracked. Tracking is only
supported for the `ITEM_VARIATION` type. | -| `quantity` | `String` | Optional | The number of items affected by the adjustment as a decimal string.
Can support up to 5 digits after the decimal point.

_Important_: The Point of Sale app and Dashboard do not currently support
decimal quantities. If a Point of Sale app or Dashboard attempts to read a
decimal quantity on inventory counts or adjustments, the quantity will be rounded
down to the nearest integer. For example, `2.5` will become `2`, and `-2.5`
will become `-3`.

Read [Decimal Quantities (BETA)](https://developer.squareup.com/docs/orders-api/what-it-does#decimal-quantities)
for more information. | -| `total_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `occurred_at` | `String` | Optional | A client-generated timestamp in RFC 3339 format that indicates when
the adjustment took place. For write actions, the `occurred_at`
timestamp cannot be older than 24 hours or in the future relative to the
time of the request. | -| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format that indicates when Square
received the adjustment. | -| `source` | [`Source Application Hash`](/doc/models/source-application.md) | Optional | Provides information about the application used to generate an inventory
change. | -| `employee_id` | `String` | Optional | The Square ID of the [Employee](./models/employee.md) responsible for the
inventory adjustment. | -| `transaction_id` | `String` | Optional | The read-only Square ID of the [Transaction][#type-transaction] that
caused the adjustment. Only relevant for payment-related state
transitions. | -| `refund_id` | `String` | Optional | The read-only Square ID of the [Refund][#type-refund] that
caused the adjustment. Only relevant for refund-related state
transitions. | -| `purchase_order_id` | `String` | Optional | The read-only Square ID of the purchase order that caused the
adjustment. Only relevant for state transitions from the Square for Retail
app. | -| `goods_receipt_id` | `String` | Optional | The read-only Square ID of the Square goods receipt that caused the
adjustment. Only relevant for state transitions from the Square for Retail
app. | - -### Example (as JSON) - -```json -{ - "id": null, - "reference_id": null, - "from_state": null, - "to_state": null, - "location_id": null, - "catalog_object_id": null, - "catalog_object_type": null, - "quantity": null, - "total_price_money": null, - "occurred_at": null, - "created_at": null, - "source": null, - "employee_id": null, - "transaction_id": null, - "refund_id": null, - "purchase_order_id": null, - "goods_receipt_id": null -} -``` - +## Inventory Adjustment + +Represents a change in state or quantity of product inventory at a +particular time and location. + +### Structure + +`InventoryAdjustment` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | A unique ID generated by Square for the
[InventoryAdjustment](#type-inventoryadjustment). | +| `reference_id` | `String` | Optional | An optional ID provided by the application to tie the
[InventoryAdjustment](#type-inventoryadjustment) to an external
system. | +| `from_state` | [`String (Inventory State)`](/doc/models/inventory-state.md) | Optional | Indicates the state of a tracked item quantity in the lifecycle of goods. | +| `to_state` | [`String (Inventory State)`](/doc/models/inventory-state.md) | Optional | Indicates the state of a tracked item quantity in the lifecycle of goods. | +| `location_id` | `String` | Optional | The Square ID of the [Location](#type-location) where the related
quantity of items are being tracked. | +| `catalog_object_id` | `String` | Optional | The Square generated ID of the
[CatalogObject](#type-catalogobject) being tracked. | +| `catalog_object_type` | `String` | Optional | The [CatalogObjectType](#type-catalogobjecttype) of the
[CatalogObject](#type-catalogobject) being tracked. Tracking is only
supported for the `ITEM_VARIATION` type. | +| `quantity` | `String` | Optional | The number of items affected by the adjustment as a decimal string.
Can support up to 5 digits after the decimal point.

_Important_: The Point of Sale app and Dashboard do not currently support
decimal quantities. If a Point of Sale app or Dashboard attempts to read a
decimal quantity on inventory counts or adjustments, the quantity will be rounded
down to the nearest integer. For example, `2.5` will become `2`, and `-2.5`
will become `-3`.

Read [Decimal Quantities (BETA)](https://developer.squareup.com/docs/orders-api/what-it-does#decimal-quantities)
for more information. | +| `total_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `occurred_at` | `String` | Optional | A client-generated timestamp in RFC 3339 format that indicates when
the adjustment took place. For write actions, the `occurred_at`
timestamp cannot be older than 24 hours or in the future relative to the
time of the request. | +| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format that indicates when Square
received the adjustment. | +| `source` | [`Source Application Hash`](/doc/models/source-application.md) | Optional | Provides information about the application used to generate an inventory
change. | +| `employee_id` | `String` | Optional | The Square ID of the [Employee](#type-employee) responsible for the
inventory adjustment. | +| `transaction_id` | `String` | Optional | The read-only Square ID of the [Transaction][#type-transaction] that
caused the adjustment. Only relevant for payment-related state
transitions. | +| `refund_id` | `String` | Optional | The read-only Square ID of the [Refund][#type-refund] that
caused the adjustment. Only relevant for refund-related state
transitions. | +| `purchase_order_id` | `String` | Optional | The read-only Square ID of the purchase order that caused the
adjustment. Only relevant for state transitions from the Square for Retail
app. | +| `goods_receipt_id` | `String` | Optional | The read-only Square ID of the Square goods receipt that caused the
adjustment. Only relevant for state transitions from the Square for Retail
app. | + +### Example (as JSON) + +```json +{ + "id": null, + "reference_id": null, + "from_state": null, + "to_state": null, + "location_id": null, + "catalog_object_id": null, + "catalog_object_type": null, + "quantity": null, + "total_price_money": null, + "occurred_at": null, + "created_at": null, + "source": null, + "employee_id": null, + "transaction_id": null, + "refund_id": null, + "purchase_order_id": null, + "goods_receipt_id": null +} +``` + diff --git a/doc/models/inventory-alert-type.md b/doc/models/inventory-alert-type.md index fcedb73e..10b8e250 100644 --- a/doc/models/inventory-alert-type.md +++ b/doc/models/inventory-alert-type.md @@ -1,15 +1,15 @@ -## Inventory Alert Type - -Indicates whether Square should alert the merchant when the inventory quantity of a [CatalogItemVariation](./models/catalog-item-variation.md) is low. - -### Enumeration - -`InventoryAlertType` - -### Fields - -| Name | Description | -| --- | --- | -| `NONE` | The variation does not display an alert. | -| `LOW_QUANTITY` | The variation generates an alert when its quantity is low. | - +## Inventory Alert Type + +Indicates whether Square should alert the merchant when the inventory quantity of a [CatalogItemVariation](#type-catalogitemvariation) is low. + +### Enumeration + +`InventoryAlertType` + +### Fields + +| Name | Description | +| --- | --- | +| `NONE` | The variation does not display an alert. | +| `LOW_QUANTITY` | The variation generates an alert when its quantity is low. | + diff --git a/doc/models/inventory-change-type.md b/doc/models/inventory-change-type.md index 861fc72f..ee1ffa8d 100644 --- a/doc/models/inventory-change-type.md +++ b/doc/models/inventory-change-type.md @@ -1,16 +1,16 @@ -## Inventory Change Type - -Indicates how the inventory change was applied to a tracked quantity of items. - -### Enumeration - -`InventoryChangeType` - -### Fields - -| Name | Description | -| --- | --- | -| `PHYSICAL_COUNT` | The change occurred as part of a physical count update. | -| `ADJUSTMENT` | The change occurred as part of the normal lifecycle of goods
(e.g., as an inventory adjustment). | -| `TRANSFER` | The change occurred as part of an inventory transfer. | - +## Inventory Change Type + +Indicates how the inventory change was applied to a tracked quantity of items. + +### Enumeration + +`InventoryChangeType` + +### Fields + +| Name | Description | +| --- | --- | +| `PHYSICAL_COUNT` | The change occurred as part of a physical count update. | +| `ADJUSTMENT` | The change occurred as part of the normal lifecycle of goods
(e.g., as an inventory adjustment). | +| `TRANSFER` | The change occurred as part of an inventory transfer. | + diff --git a/doc/models/inventory-change.md b/doc/models/inventory-change.md index 98a41838..d73844d3 100644 --- a/doc/models/inventory-change.md +++ b/doc/models/inventory-change.md @@ -1,30 +1,30 @@ -## Inventory Change - -Represents a single physical count, inventory, adjustment, or transfer -that is part of the history of inventory changes for a particular -[CatalogObject](./models/catalog-object.md). - -### Structure - -`InventoryChange` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `type` | [`String (Inventory Change Type)`](/doc/models/inventory-change-type.md) | Optional | Indicates how the inventory change was applied to a tracked quantity of items. | -| `physical_count` | [`Inventory Physical Count Hash`](/doc/models/inventory-physical-count.md) | Optional | Represents the quantity of an item variation that is physically present
at a specific location, verified by a seller or a seller's employee. For example,
a physical count might come from an employee counting the item variations on
hand or from syncing with an external system. | -| `adjustment` | [`Inventory Adjustment Hash`](/doc/models/inventory-adjustment.md) | Optional | Represents a change in state or quantity of product inventory at a
particular time and location. | -| `transfer` | [`Inventory Transfer Hash`](/doc/models/inventory-transfer.md) | Optional | Represents the transfer of a quantity of product inventory at a
particular time from one location to another. | - -### Example (as JSON) - -```json -{ - "type": null, - "physical_count": null, - "adjustment": null, - "transfer": null -} -``` - +## Inventory Change + +Represents a single physical count, inventory, adjustment, or transfer +that is part of the history of inventory changes for a particular +[CatalogObject](#type-catalogobject). + +### Structure + +`InventoryChange` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `type` | [`String (Inventory Change Type)`](/doc/models/inventory-change-type.md) | Optional | Indicates how the inventory change was applied to a tracked quantity of items. | +| `physical_count` | [`Inventory Physical Count Hash`](/doc/models/inventory-physical-count.md) | Optional | Represents the quantity of an item variation that is physically present
at a specific location, verified by a seller or a seller's employee. For example,
a physical count might come from an employee counting the item variations on
hand or from syncing with an external system. | +| `adjustment` | [`Inventory Adjustment Hash`](/doc/models/inventory-adjustment.md) | Optional | Represents a change in state or quantity of product inventory at a
particular time and location. | +| `transfer` | [`Inventory Transfer Hash`](/doc/models/inventory-transfer.md) | Optional | Represents the transfer of a quantity of product inventory at a
particular time from one location to another. | + +### Example (as JSON) + +```json +{ + "type": null, + "physical_count": null, + "adjustment": null, + "transfer": null +} +``` + diff --git a/doc/models/inventory-count.md b/doc/models/inventory-count.md index 5c51feee..410f0d79 100644 --- a/doc/models/inventory-count.md +++ b/doc/models/inventory-count.md @@ -1,34 +1,34 @@ -## Inventory Count - -Represents Square's estimated quantity of items in a particular state at a -particular location based on the known history of physical counts and -inventory adjustments - -### Structure - -`InventoryCount` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `catalog_object_id` | `String` | Optional | The Square generated ID of the
[CatalogObject](./models/catalog-object.md) being tracked. | -| `catalog_object_type` | `String` | Optional | The [CatalogObjectType](./models/catalog-object-type.md) of the
[CatalogObject](./models/catalog-object.md) being tracked. Tracking is only
supported for the `ITEM_VARIATION` type. | -| `state` | [`String (Inventory State)`](/doc/models/inventory-state.md) | Optional | Indicates the state of a tracked item quantity in the lifecycle of goods. | -| `location_id` | `String` | Optional | The Square ID of the [Location](./models/location.md) where the related
quantity of items are being tracked. | -| `quantity` | `String` | Optional | The number of items in the count as a decimal string.
Can support up to 5 digits after the decimal point.

_Important_: The Point of Sale app and Dashboard do not currently support
decimal quantities. If a Point of Sale app or Dashboard attempts to read a
decimal quantity on inventory counts or adjustments, the quantity will be rounded
down to the nearest integer. For example, `2.5` will become `2`, and `-2.5`
will become `-3`.

Read [Decimal Quantities (BETA)](https://developer.squareup.com/docs/orders-api/what-it-does#decimal-quantities)
for more information. | -| `calculated_at` | `String` | Optional | A read-only timestamp in RFC 3339 format that indicates when Square
received the most recent physical count or adjustment that had an affect
on the estimated count. | - -### Example (as JSON) - -```json -{ - "catalog_object_id": null, - "catalog_object_type": null, - "state": null, - "location_id": null, - "quantity": null, - "calculated_at": null -} -``` - +## Inventory Count + +Represents Square's estimated quantity of items in a particular state at a +particular location based on the known history of physical counts and +inventory adjustments + +### Structure + +`InventoryCount` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `catalog_object_id` | `String` | Optional | The Square generated ID of the
[CatalogObject](#type-catalogobject) being tracked. | +| `catalog_object_type` | `String` | Optional | The [CatalogObjectType](#type-catalogobjecttype) of the
[CatalogObject](#type-catalogobject) being tracked. Tracking is only
supported for the `ITEM_VARIATION` type. | +| `state` | [`String (Inventory State)`](/doc/models/inventory-state.md) | Optional | Indicates the state of a tracked item quantity in the lifecycle of goods. | +| `location_id` | `String` | Optional | The Square ID of the [Location](#type-location) where the related
quantity of items are being tracked. | +| `quantity` | `String` | Optional | The number of items in the count as a decimal string.
Can support up to 5 digits after the decimal point.

_Important_: The Point of Sale app and Dashboard do not currently support
decimal quantities. If a Point of Sale app or Dashboard attempts to read a
decimal quantity on inventory counts or adjustments, the quantity will be rounded
down to the nearest integer. For example, `2.5` will become `2`, and `-2.5`
will become `-3`.

Read [Decimal Quantities (BETA)](https://developer.squareup.com/docs/orders-api/what-it-does#decimal-quantities)
for more information. | +| `calculated_at` | `String` | Optional | A read-only timestamp in RFC 3339 format that indicates when Square
received the most recent physical count or adjustment that had an affect
on the estimated count. | + +### Example (as JSON) + +```json +{ + "catalog_object_id": null, + "catalog_object_type": null, + "state": null, + "location_id": null, + "quantity": null, + "calculated_at": null +} +``` + diff --git a/doc/models/inventory-physical-count.md b/doc/models/inventory-physical-count.md index 63e40a93..eb552264 100644 --- a/doc/models/inventory-physical-count.md +++ b/doc/models/inventory-physical-count.md @@ -1,45 +1,45 @@ -## Inventory Physical Count - -Represents the quantity of an item variation that is physically present -at a specific location, verified by a seller or a seller's employee. For example, -a physical count might come from an employee counting the item variations on -hand or from syncing with an external system. - -### Structure - -`InventoryPhysicalCount` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | A unique ID generated by Square for the
[InventoryPhysicalCount](./models/inventory-physical-count.md). | -| `reference_id` | `String` | Optional | An optional ID provided by the application to tie the
[InventoryPhysicalCount](./models/inventory-physical-count.md) to an external
system. | -| `catalog_object_id` | `String` | Optional | The Square generated ID of the
[CatalogObject](./models/catalog-object.md) being tracked. | -| `catalog_object_type` | `String` | Optional | The [CatalogObjectType](./models/catalog-object-type.md) of the
[CatalogObject](./models/catalog-object.md) being tracked. Tracking is only
supported for the `ITEM_VARIATION` type. | -| `state` | [`String (Inventory State)`](/doc/models/inventory-state.md) | Optional | Indicates the state of a tracked item quantity in the lifecycle of goods. | -| `location_id` | `String` | Optional | The Square ID of the [Location](./models/location.md) where the related
quantity of items are being tracked. | -| `quantity` | `String` | Optional | The number of items affected by the physical count as a decimal string.
Can support up to 5 digits after the decimal point.

_Important_: The Point of Sale app and Dashboard do not currently support
decimal quantities. If a Point of Sale app or Dashboard attempts to read a
decimal quantity on inventory counts or adjustments, the quantity will be rounded
down to the nearest integer. For example, `2.5` will become `2`, and `-2.5`
will become `-3`.

Read [Decimal Quantities (BETA)](https://developer.squareup.com/docs/orders-api/what-it-does#decimal-quantities)
for more information. | -| `source` | [`Source Application Hash`](/doc/models/source-application.md) | Optional | Provides information about the application used to generate an inventory
change. | -| `employee_id` | `String` | Optional | The Square ID of the [Employee](./models/employee.md) responsible for the
physical count. | -| `occurred_at` | `String` | Optional | A client-generated timestamp in RFC 3339 format that indicates when
the physical count took place. For write actions, the `occurred_at`
timestamp cannot be older than 24 hours or in the future relative to the
time of the request. | -| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format that indicates when Square
received the physical count. | - -### Example (as JSON) - -```json -{ - "id": null, - "reference_id": null, - "catalog_object_id": null, - "catalog_object_type": null, - "state": null, - "location_id": null, - "quantity": null, - "source": null, - "employee_id": null, - "occurred_at": null, - "created_at": null -} -``` - +## Inventory Physical Count + +Represents the quantity of an item variation that is physically present +at a specific location, verified by a seller or a seller's employee. For example, +a physical count might come from an employee counting the item variations on +hand or from syncing with an external system. + +### Structure + +`InventoryPhysicalCount` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | A unique ID generated by Square for the
[InventoryPhysicalCount](#type-inventoryphysicalcount). | +| `reference_id` | `String` | Optional | An optional ID provided by the application to tie the
[InventoryPhysicalCount](#type-inventoryphysicalcount) to an external
system. | +| `catalog_object_id` | `String` | Optional | The Square generated ID of the
[CatalogObject](#type-catalogobject) being tracked. | +| `catalog_object_type` | `String` | Optional | The [CatalogObjectType](#type-catalogobjecttype) of the
[CatalogObject](#type-catalogobject) being tracked. Tracking is only
supported for the `ITEM_VARIATION` type. | +| `state` | [`String (Inventory State)`](/doc/models/inventory-state.md) | Optional | Indicates the state of a tracked item quantity in the lifecycle of goods. | +| `location_id` | `String` | Optional | The Square ID of the [Location](#type-location) where the related
quantity of items are being tracked. | +| `quantity` | `String` | Optional | The number of items affected by the physical count as a decimal string.
Can support up to 5 digits after the decimal point.

_Important_: The Point of Sale app and Dashboard do not currently support
decimal quantities. If a Point of Sale app or Dashboard attempts to read a
decimal quantity on inventory counts or adjustments, the quantity will be rounded
down to the nearest integer. For example, `2.5` will become `2`, and `-2.5`
will become `-3`.

Read [Decimal Quantities (BETA)](https://developer.squareup.com/docs/orders-api/what-it-does#decimal-quantities)
for more information. | +| `source` | [`Source Application Hash`](/doc/models/source-application.md) | Optional | Provides information about the application used to generate an inventory
change. | +| `employee_id` | `String` | Optional | The Square ID of the [Employee](#type-employee) responsible for the
physical count. | +| `occurred_at` | `String` | Optional | A client-generated timestamp in RFC 3339 format that indicates when
the physical count took place. For write actions, the `occurred_at`
timestamp cannot be older than 24 hours or in the future relative to the
time of the request. | +| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format that indicates when Square
received the physical count. | + +### Example (as JSON) + +```json +{ + "id": null, + "reference_id": null, + "catalog_object_id": null, + "catalog_object_type": null, + "state": null, + "location_id": null, + "quantity": null, + "source": null, + "employee_id": null, + "occurred_at": null, + "created_at": null +} +``` + diff --git a/doc/models/inventory-state.md b/doc/models/inventory-state.md index f65b86eb..b79f44bf 100644 --- a/doc/models/inventory-state.md +++ b/doc/models/inventory-state.md @@ -1,25 +1,25 @@ -## Inventory State - -Indicates the state of a tracked item quantity in the lifecycle of goods. - -### Enumeration - -`InventoryState` - -### Fields - -| Name | Description | -| --- | --- | -| `CUSTOM` | The related quantity of items are in a custom state. **READ-ONLY**:
the Inventory API cannot move quantities to or from this state. | -| `IN_STOCK` | The related quantity of items are on hand and available for sale. | -| `SOLD` | The related quantity of items were sold as part of an itemized
transaction. Quantities in the `SOLD` state are no longer tracked. | -| `RETURNED_BY_CUSTOMER` | The related quantity of items were returned through the Square Point
of Sale application, but are not yet available for sale. **READ-ONLY**:
the Inventory API cannot move quantities to or from this state. | -| `RESERVED_FOR_SALE` | The related quantity of items are on hand, but not currently
available for sale. **READ-ONLY**: the Inventory API cannot move
quantities to or from this state. | -| `SOLD_ONLINE` | The related quantity of items were sold online. **READ-ONLY**: the
Inventory API cannot move quantities to or from this state. | -| `ORDERED_FROM_VENDOR` | The related quantity of items were ordered from a vendor but not yet
received. **READ-ONLY**: the Inventory API cannot move quantities to or
from this state. | -| `RECEIVED_FROM_VENDOR` | The related quantity of items were received from a vendor but are
not yet available for sale. **READ-ONLY**: the Inventory API cannot move
quantities to or from this state. | -| `IN_TRANSIT_TO` | The related quantity of items are in transit between locations.
*READ-ONLY**: the Inventory API cannot move quantities to or from this
state. | -| `NONE` | A placeholder indicating that the related quantity of items are not
currently tracked in Square. Transferring quantities from the `NONE` state
to a tracked state (e.g., `IN_STOCK`) introduces stock into the system. | -| `WASTE` | The related quantity of items are lost or damaged and cannot be
sold. | -| `UNLINKED_RETURN` | The related quantity of items were returned but not linked to a
previous transaction. Unlinked returns are not tracked in Square.
Transferring a quantity from `UNLINKED_RETURN` to a tracked state (e.g.,
`IN_STOCK`) introduces new stock into the system. | - +## Inventory State + +Indicates the state of a tracked item quantity in the lifecycle of goods. + +### Enumeration + +`InventoryState` + +### Fields + +| Name | Description | +| --- | --- | +| `CUSTOM` | The related quantity of items are in a custom state. **READ-ONLY**:
the Inventory API cannot move quantities to or from this state. | +| `IN_STOCK` | The related quantity of items are on hand and available for sale. | +| `SOLD` | The related quantity of items were sold as part of an itemized
transaction. Quantities in the `SOLD` state are no longer tracked. | +| `RETURNED_BY_CUSTOMER` | The related quantity of items were returned through the Square Point
of Sale application, but are not yet available for sale. **READ-ONLY**:
the Inventory API cannot move quantities to or from this state. | +| `RESERVED_FOR_SALE` | The related quantity of items are on hand, but not currently
available for sale. **READ-ONLY**: the Inventory API cannot move
quantities to or from this state. | +| `SOLD_ONLINE` | The related quantity of items were sold online. **READ-ONLY**: the
Inventory API cannot move quantities to or from this state. | +| `ORDERED_FROM_VENDOR` | The related quantity of items were ordered from a vendor but not yet
received. **READ-ONLY**: the Inventory API cannot move quantities to or
from this state. | +| `RECEIVED_FROM_VENDOR` | The related quantity of items were received from a vendor but are
not yet available for sale. **READ-ONLY**: the Inventory API cannot move
quantities to or from this state. | +| `IN_TRANSIT_TO` | The related quantity of items are in transit between locations.
*READ-ONLY**: the Inventory API cannot move quantities to or from this
state. | +| `NONE` | A placeholder indicating that the related quantity of items are not
currently tracked in Square. Transferring quantities from the `NONE` state
to a tracked state (e.g., `IN_STOCK`) introduces stock into the system. | +| `WASTE` | The related quantity of items are lost or damaged and cannot be
sold. | +| `UNLINKED_RETURN` | The related quantity of items were returned but not linked to a
previous transaction. Unlinked returns are not tracked in Square.
Transferring a quantity from `UNLINKED_RETURN` to a tracked state (e.g.,
`IN_STOCK`) introduces new stock into the system. | + diff --git a/doc/models/inventory-transfer.md b/doc/models/inventory-transfer.md index 556678b3..d4aa604a 100644 --- a/doc/models/inventory-transfer.md +++ b/doc/models/inventory-transfer.md @@ -1,45 +1,45 @@ -## Inventory Transfer - -Represents the transfer of a quantity of product inventory at a -particular time from one location to another. - -### Structure - -`InventoryTransfer` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | A unique ID generated by Square for the
[InventoryTransfer](./models/inventory-transfer.md). | -| `reference_id` | `String` | Optional | An optional ID provided by the application to tie the
[InventoryTransfer](./models/inventory-transfer.md) to an external system. | -| `state` | [`String (Inventory State)`](/doc/models/inventory-state.md) | Optional | Indicates the state of a tracked item quantity in the lifecycle of goods. | -| `from_location_id` | `String` | Optional | The Square ID of the [Location](./models/location.md) where the related
quantity of items were tracked before the transfer. | -| `to_location_id` | `String` | Optional | The Square ID of the [Location](./models/location.md) where the related
quantity of items were tracked after the transfer. | -| `catalog_object_id` | `String` | Optional | The Square generated ID of the
[CatalogObject](./models/catalog-object.md) being tracked. | -| `catalog_object_type` | `String` | Optional | The [CatalogObjectType](./models/catalog-object-type.md) of the
[CatalogObject](./models/catalog-object.md) being tracked.Tracking is only
supported for the `ITEM_VARIATION` type. | -| `quantity` | `String` | Optional | The number of items affected by the transfer as a decimal string.
Can support up to 5 digits after the decimal point.

_Important_: The Point of Sale app and Dashboard do not currently support
decimal quantities. If a Point of Sale app or Dashboard attempts to read a
decimal quantity on inventory counts or adjustments, the quantity will be rounded
down to the nearest integer. For example, `2.5` will become `2`, and `-2.5`
will become `-3`.

Read [Decimal Quantities (BETA)](https://developer.squareup.com/docs/orders-api/what-it-does#decimal-quantities)
for more information. | -| `occurred_at` | `String` | Optional | A client-generated timestamp in RFC 3339 format that indicates when
the transfer took place. For write actions, the `occurred_at` timestamp
cannot be older than 24 hours or in the future relative to the time of the
request. | -| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format that indicates when Square
received the transfer request. | -| `source` | [`Source Application Hash`](/doc/models/source-application.md) | Optional | Provides information about the application used to generate an inventory
change. | -| `employee_id` | `String` | Optional | The Square ID of the [Employee](./models/employee.md) responsible for the
inventory transfer. | - -### Example (as JSON) - -```json -{ - "id": null, - "reference_id": null, - "state": null, - "from_location_id": null, - "to_location_id": null, - "catalog_object_id": null, - "catalog_object_type": null, - "quantity": null, - "occurred_at": null, - "created_at": null, - "source": null, - "employee_id": null -} -``` - +## Inventory Transfer + +Represents the transfer of a quantity of product inventory at a +particular time from one location to another. + +### Structure + +`InventoryTransfer` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | A unique ID generated by Square for the
[InventoryTransfer](#type-inventorytransfer). | +| `reference_id` | `String` | Optional | An optional ID provided by the application to tie the
[InventoryTransfer](#type-inventorytransfer) to an external system. | +| `state` | [`String (Inventory State)`](/doc/models/inventory-state.md) | Optional | Indicates the state of a tracked item quantity in the lifecycle of goods. | +| `from_location_id` | `String` | Optional | The Square ID of the [Location](#type-location) where the related
quantity of items were tracked before the transfer. | +| `to_location_id` | `String` | Optional | The Square ID of the [Location](#type-location) where the related
quantity of items were tracked after the transfer. | +| `catalog_object_id` | `String` | Optional | The Square generated ID of the
[CatalogObject](#type-catalogobject) being tracked. | +| `catalog_object_type` | `String` | Optional | The [CatalogObjectType](#type-catalogobjecttype) of the
[CatalogObject](#type-catalogobject) being tracked.Tracking is only
supported for the `ITEM_VARIATION` type. | +| `quantity` | `String` | Optional | The number of items affected by the transfer as a decimal string.
Can support up to 5 digits after the decimal point.

_Important_: The Point of Sale app and Dashboard do not currently support
decimal quantities. If a Point of Sale app or Dashboard attempts to read a
decimal quantity on inventory counts or adjustments, the quantity will be rounded
down to the nearest integer. For example, `2.5` will become `2`, and `-2.5`
will become `-3`.

Read [Decimal Quantities (BETA)](https://developer.squareup.com/docs/orders-api/what-it-does#decimal-quantities)
for more information. | +| `occurred_at` | `String` | Optional | A client-generated timestamp in RFC 3339 format that indicates when
the transfer took place. For write actions, the `occurred_at` timestamp
cannot be older than 24 hours or in the future relative to the time of the
request. | +| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format that indicates when Square
received the transfer request. | +| `source` | [`Source Application Hash`](/doc/models/source-application.md) | Optional | Provides information about the application used to generate an inventory
change. | +| `employee_id` | `String` | Optional | The Square ID of the [Employee](#type-employee) responsible for the
inventory transfer. | + +### Example (as JSON) + +```json +{ + "id": null, + "reference_id": null, + "state": null, + "from_location_id": null, + "to_location_id": null, + "catalog_object_id": null, + "catalog_object_type": null, + "quantity": null, + "occurred_at": null, + "created_at": null, + "source": null, + "employee_id": null +} +``` + diff --git a/doc/models/item-variation-location-overrides.md b/doc/models/item-variation-location-overrides.md index ff58a66e..8dc15059 100644 --- a/doc/models/item-variation-location-overrides.md +++ b/doc/models/item-variation-location-overrides.md @@ -1,32 +1,32 @@ -## Item Variation Location Overrides - -Price and inventory alerting overrides for a [CatalogItemVariation](./models/catalog-item-variation.md) at a specific [location](./models/location.md). - -### Structure - -`ItemVariationLocationOverrides` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Optional | The ID of the [location](./models/location.md). | -| `price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `pricing_type` | [`String (Catalog Pricing Type)`](/doc/models/catalog-pricing-type.md) | Optional | Indicates whether the price of a [CatalogItemVariation](./models/catalog-item-variation.md) should be entered manually at the time of sale. | -| `track_inventory` | `Boolean` | Optional | If `true`, inventory tracking is active for the [CatalogItemVariation](./models/catalog-item-variation.md) at this [location](./models/location.md). | -| `inventory_alert_type` | [`String (Inventory Alert Type)`](/doc/models/inventory-alert-type.md) | Optional | Indicates whether Square should alert the merchant when the inventory quantity of a [CatalogItemVariation](./models/catalog-item-variation.md) is low. | -| `inventory_alert_threshold` | `Long` | Optional | If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`
is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.

This value is always an integer. | - -### Example (as JSON) - -```json -{ - "location_id": null, - "price_money": null, - "pricing_type": null, - "track_inventory": null, - "inventory_alert_type": null, - "inventory_alert_threshold": null -} -``` - +## Item Variation Location Overrides + +Price and inventory alerting overrides for a [CatalogItemVariation](#type-catalogitemvariation) at a specific [location](#type-location). + +### Structure + +`ItemVariationLocationOverrides` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Optional | The ID of the [location](#type-location). | +| `price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `pricing_type` | [`String (Catalog Pricing Type)`](/doc/models/catalog-pricing-type.md) | Optional | Indicates whether the price of a [CatalogItemVariation](#type-catalogitemvariation) should be entered manually at the time of sale. | +| `track_inventory` | `Boolean` | Optional | If `true`, inventory tracking is active for the [CatalogItemVariation](#type-catalogitemvariation) at this [location](#type-location). | +| `inventory_alert_type` | [`String (Inventory Alert Type)`](/doc/models/inventory-alert-type.md) | Optional | Indicates whether Square should alert the merchant when the inventory quantity of a [CatalogItemVariation](#type-catalogitemvariation) is low. | +| `inventory_alert_threshold` | `Long` | Optional | If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`
is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.

This value is always an integer. | + +### Example (as JSON) + +```json +{ + "location_id": null, + "price_money": null, + "pricing_type": null, + "track_inventory": null, + "inventory_alert_type": null, + "inventory_alert_threshold": null +} +``` + diff --git a/doc/models/list-additional-recipient-receivable-refunds-request.md b/doc/models/list-additional-recipient-receivable-refunds-request.md index 494f121c..b2ea9e70 100644 --- a/doc/models/list-additional-recipient-receivable-refunds-request.md +++ b/doc/models/list-additional-recipient-receivable-refunds-request.md @@ -1,29 +1,29 @@ -## List Additional Recipient Receivable Refunds Request - -Defines the query parameters that can be included in -a request to the ListAdditionalRecipientReceivableRefunds endpoint. - -### Structure - -`ListAdditionalRecipientReceivableRefundsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | -| `end_time` | `String` | Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "begin_time": null, - "end_time": null, - "sort_order": null, - "cursor": null -} -``` - +## List Additional Recipient Receivable Refunds Request + +Defines the query parameters that can be included in +a request to the ListAdditionalRecipientReceivableRefunds endpoint. + +### Structure + +`ListAdditionalRecipientReceivableRefundsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | +| `end_time` | `String` | Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "begin_time": null, + "end_time": null, + "sort_order": null, + "cursor": null +} +``` + diff --git a/doc/models/list-additional-recipient-receivable-refunds-response.md b/doc/models/list-additional-recipient-receivable-refunds-response.md index f3b894ee..af753b00 100644 --- a/doc/models/list-additional-recipient-receivable-refunds-response.md +++ b/doc/models/list-additional-recipient-receivable-refunds-response.md @@ -1,39 +1,39 @@ -## List Additional Recipient Receivable Refunds Response - -Defines the fields that are included in the response body of -a request to the ListAdditionalRecipientReceivableRefunds endpoint. - -One of `errors` or `additional_recipient_receivable_refunds` is present in a given response (never both). - -### Structure - -`ListAdditionalRecipientReceivableRefundsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `receivable_refunds` | [`Array`](/doc/models/additional-recipient-receivable-refund.md) | Optional | An array of AdditionalRecipientReceivableRefunds that match your query. | -| `cursor` | `String` | Optional | A pagination cursor for retrieving the next set of results,
if any remain. Provide this value as the `cursor` parameter in a subsequent
request to this endpoint.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "receivable_refunds": [ - { - "id": "Ge2OT7KA6XAg1GC15qs5S", - "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF", - "refund_id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW", - "transaction_location_id": "18YC4JDH91E1H", - "amount_money": { - "amount": 10, - "currency": "USD" - }, - "created_at": "2016-01-20T22:57:56Z" - } - ] -} -``` - +## List Additional Recipient Receivable Refunds Response + +Defines the fields that are included in the response body of +a request to the ListAdditionalRecipientReceivableRefunds endpoint. + +One of `errors` or `additional_recipient_receivable_refunds` is present in a given response (never both). + +### Structure + +`ListAdditionalRecipientReceivableRefundsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `receivable_refunds` | [`Array`](/doc/models/additional-recipient-receivable-refund.md) | Optional | An array of AdditionalRecipientReceivableRefunds that match your query. | +| `cursor` | `String` | Optional | A pagination cursor for retrieving the next set of results,
if any remain. Provide this value as the `cursor` parameter in a subsequent
request to this endpoint.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "receivable_refunds": [ + { + "id": "Ge2OT7KA6XAg1GC15qs5S", + "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF", + "refund_id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW", + "transaction_location_id": "18YC4JDH91E1H", + "amount_money": { + "amount": 10, + "currency": "USD" + }, + "created_at": "2016-01-20T22:57:56Z" + } + ] +} +``` + diff --git a/doc/models/list-additional-recipient-receivables-request.md b/doc/models/list-additional-recipient-receivables-request.md index 2faccc3c..6698fa98 100644 --- a/doc/models/list-additional-recipient-receivables-request.md +++ b/doc/models/list-additional-recipient-receivables-request.md @@ -1,29 +1,29 @@ -## List Additional Recipient Receivables Request - -Defines the query parameters that can be included in -a request to the ListAdditionalRecipientReceivables endpoint. - -### Structure - -`ListAdditionalRecipientReceivablesRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | -| `end_time` | `String` | Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "begin_time": null, - "end_time": null, - "sort_order": null, - "cursor": null -} -``` - +## List Additional Recipient Receivables Request + +Defines the query parameters that can be included in +a request to the ListAdditionalRecipientReceivables endpoint. + +### Structure + +`ListAdditionalRecipientReceivablesRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | +| `end_time` | `String` | Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "begin_time": null, + "end_time": null, + "sort_order": null, + "cursor": null +} +``` + diff --git a/doc/models/list-additional-recipient-receivables-response.md b/doc/models/list-additional-recipient-receivables-response.md index ab8b3aa9..4d626d03 100644 --- a/doc/models/list-additional-recipient-receivables-response.md +++ b/doc/models/list-additional-recipient-receivables-response.md @@ -1,51 +1,51 @@ -## List Additional Recipient Receivables Response - -Defines the fields that are included in the response body of -a request to the ListAdditionalRecipientReceivables endpoint. - -One of `errors` or `additional_recipient_receivables` is present in a given response (never both). - -### Structure - -`ListAdditionalRecipientReceivablesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `receivables` | [`Array`](/doc/models/additional-recipient-receivable.md) | Optional | An array of AdditionalRecipientReceivables that match your query. | -| `cursor` | `String` | Optional | A pagination cursor for retrieving the next set of results,
if any remain. Provide this value as the `cursor` parameter in a subsequent
request to this endpoint.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "receivables": [ - { - "id": "ISu5xwxJ5v0CMJTQq7RvqyMF", - "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", - "transaction_location_id": "18YC4JDH91E1H", - "amount_money": { - "amount": 20, - "currency": "USD" - }, - "created_at": "2016-01-19T15:12:41Z", - "refunds": [ - { - "id": "Ge2OT7KA6XAg1GC15qs5S", - "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF", - "refund_id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW", - "transaction_location_id": "18YC4JDH91E1H", - "amount_money": { - "amount": 10, - "currency": "USD" - }, - "created_at": "2016-01-20T22:57:56Z" - } - ] - } - ] -} -``` - +## List Additional Recipient Receivables Response + +Defines the fields that are included in the response body of +a request to the ListAdditionalRecipientReceivables endpoint. + +One of `errors` or `additional_recipient_receivables` is present in a given response (never both). + +### Structure + +`ListAdditionalRecipientReceivablesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `receivables` | [`Array`](/doc/models/additional-recipient-receivable.md) | Optional | An array of AdditionalRecipientReceivables that match your query. | +| `cursor` | `String` | Optional | A pagination cursor for retrieving the next set of results,
if any remain. Provide this value as the `cursor` parameter in a subsequent
request to this endpoint.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "receivables": [ + { + "id": "ISu5xwxJ5v0CMJTQq7RvqyMF", + "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", + "transaction_location_id": "18YC4JDH91E1H", + "amount_money": { + "amount": 20, + "currency": "USD" + }, + "created_at": "2016-01-19T15:12:41Z", + "refunds": [ + { + "id": "Ge2OT7KA6XAg1GC15qs5S", + "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF", + "refund_id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW", + "transaction_location_id": "18YC4JDH91E1H", + "amount_money": { + "amount": 10, + "currency": "USD" + }, + "created_at": "2016-01-20T22:57:56Z" + } + ] + } + ] +} +``` + diff --git a/doc/models/list-break-types-request.md b/doc/models/list-break-types-request.md index a4c0848a..867159e8 100644 --- a/doc/models/list-break-types-request.md +++ b/doc/models/list-break-types-request.md @@ -1,26 +1,26 @@ -## List Break Types Request - -A request for a filtered set of `BreakType` objects - -### Structure - -`ListBreakTypesRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Optional | Filter Break Types returned to only those that are associated with the
specified location. | -| `limit` | `Integer` | Optional | Maximum number of Break Types to return per page. Can range between 1
and 200. The default is the maximum at 200. | -| `cursor` | `String` | Optional | Pointer to the next page of Break Type results to fetch. | - -### Example (as JSON) - -```json -{ - "location_id": null, - "limit": null, - "cursor": null -} -``` - +## List Break Types Request + +A request for a filtered set of `BreakType` objects + +### Structure + +`ListBreakTypesRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Optional | Filter Break Types returned to only those that are associated with the
specified location. | +| `limit` | `Integer` | Optional | Maximum number of Break Types to return per page. Can range between 1
and 200. The default is the maximum at 200. | +| `cursor` | `String` | Optional | Pointer to the next page of Break Type results to fetch. | + +### Example (as JSON) + +```json +{ + "location_id": null, + "limit": null, + "cursor": null +} +``` + diff --git a/doc/models/list-break-types-response.md b/doc/models/list-break-types-response.md index c3aab5a1..99701dc1 100644 --- a/doc/models/list-break-types-response.md +++ b/doc/models/list-break-types-response.md @@ -1,48 +1,48 @@ -## List Break Types Response - -The response to a request for a set of `BreakTypes`. Contains -the requested `BreakType` objects. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`ListBreakTypesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `break_types` | [`Array`](/doc/models/break-type.md) | Optional | A page of `BreakType` results. | -| `cursor` | `String` | Optional | Value supplied in the subsequent request to fetch the next next page
of Break Type results. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "break_types": [ - { - "id": "REGS1EQR1TPZ5", - "location_id": "PAA1RJZZKXBFG", - "break_name": "Coffee Break", - "expected_duration": "PT5M", - "is_paid": false, - "version": 1, - "created_at": "2019-01-22T20:47:37Z", - "updated_at": "2019-01-22T20:47:37Z" - }, - { - "id": "92EPDRQKJ5088", - "location_id": "PAA1RJZZKXBFG", - "break_name": "Lunch Break", - "expected_duration": "PT1H", - "is_paid": true, - "version": 3, - "created_at": "2019-01-25T19:26:30Z", - "updated_at": "2019-01-25T19:26:30Z" - } - ], - "cursor": "2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED" -} -``` - +## List Break Types Response + +The response to a request for a set of `BreakTypes`. Contains +the requested `BreakType` objects. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`ListBreakTypesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `break_types` | [`Array`](/doc/models/break-type.md) | Optional | A page of `BreakType` results. | +| `cursor` | `String` | Optional | Value supplied in the subsequent request to fetch the next next page
of Break Type results. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "break_types": [ + { + "id": "REGS1EQR1TPZ5", + "location_id": "PAA1RJZZKXBFG", + "break_name": "Coffee Break", + "expected_duration": "PT5M", + "is_paid": false, + "version": 1, + "created_at": "2019-01-22T20:47:37Z", + "updated_at": "2019-01-22T20:47:37Z" + }, + { + "id": "92EPDRQKJ5088", + "location_id": "PAA1RJZZKXBFG", + "break_name": "Lunch Break", + "expected_duration": "PT1H", + "is_paid": true, + "version": 3, + "created_at": "2019-01-25T19:26:30Z", + "updated_at": "2019-01-25T19:26:30Z" + } + ], + "cursor": "2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED" +} +``` + diff --git a/doc/models/list-catalog-request.md b/doc/models/list-catalog-request.md index 6c44e52c..e6592316 100644 --- a/doc/models/list-catalog-request.md +++ b/doc/models/list-catalog-request.md @@ -1,22 +1,22 @@ -## List Catalog Request - -### Structure - -`ListCatalogRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `cursor` | `String` | Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `types` | `String` | Optional | An optional case-insensitive, comma-separated list of object types to retrieve, for example
`ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.

The legal values are taken from the [CatalogObjectType](./models/catalog-object-type.md)
enumeration, namely `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, or `IMAGE`. | - -### Example (as JSON) - -```json -{ - "cursor": null, - "types": null -} -``` - +## List Catalog Request + +### Structure + +`ListCatalogRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `cursor` | `String` | Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `types` | `String` | Optional | An optional case-insensitive, comma-separated list of object types to retrieve, for example
`ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.

The legal values are taken from the [CatalogObjectType](#type-catalogobjecttype)
enumeration, namely `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, or `IMAGE`. | + +### Example (as JSON) + +```json +{ + "cursor": null, + "types": null +} +``` + diff --git a/doc/models/list-catalog-response.md b/doc/models/list-catalog-response.md index aa035661..263691ab 100644 --- a/doc/models/list-catalog-response.md +++ b/doc/models/list-catalog-response.md @@ -1,49 +1,49 @@ -## List Catalog Response - -### Structure - -`ListCatalogResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset, this is the final response.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `objects` | [`Array`](/doc/models/catalog-object.md) | Optional | The [CatalogObject](./models/catalog-object.md)s returned. | - -### Example (as JSON) - -```json -{ - "objects": [ - { - "type": "CATEGORY", - "id": "5ZYQZZ2IECPVJ2IJ5KQPRDC3", - "updated_at": "2017-02-21T14:50:26.495Z", - "version": 1487688626495, - "is_deleted": false, - "present_at_all_locations": true, - "category_data": { - "name": "Beverages" - } - }, - { - "type": "TAX", - "id": "L5R47DGBZOOVKCAFIXC56AEN", - "updated_at": "2017-02-21T14:50:26.495Z", - "version": 1487688626495, - "is_deleted": false, - "present_at_all_locations": true, - "tax_data": { - "name": "Sales Tax", - "calculation_phase": "TAX_SUBTOTAL_PHASE", - "inclusion_type": "ADDITIVE", - "percentage": "5.0", - "enabled": true - } - } - ] -} -``` - +## List Catalog Response + +### Structure + +`ListCatalogResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset, this is the final response.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `objects` | [`Array`](/doc/models/catalog-object.md) | Optional | The [CatalogObject](#type-catalogobject)s returned. | + +### Example (as JSON) + +```json +{ + "objects": [ + { + "type": "CATEGORY", + "id": "5ZYQZZ2IECPVJ2IJ5KQPRDC3", + "updated_at": "2017-02-21T14:50:26.495Z", + "version": 1487688626495, + "is_deleted": false, + "present_at_all_locations": true, + "category_data": { + "name": "Beverages" + } + }, + { + "type": "TAX", + "id": "L5R47DGBZOOVKCAFIXC56AEN", + "updated_at": "2017-02-21T14:50:26.495Z", + "version": 1487688626495, + "is_deleted": false, + "present_at_all_locations": true, + "tax_data": { + "name": "Sales Tax", + "calculation_phase": "TAX_SUBTOTAL_PHASE", + "inclusion_type": "ADDITIVE", + "percentage": "5.0", + "enabled": true + } + } + ] +} +``` + diff --git a/doc/models/list-customers-request.md b/doc/models/list-customers-request.md index db11fbad..80dd25ef 100644 --- a/doc/models/list-customers-request.md +++ b/doc/models/list-customers-request.md @@ -1,27 +1,27 @@ -## List Customers Request - -Defines the query parameters that can be provided in a request to the -ListCustomers endpoint. - -### Structure - -`ListCustomersRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `sort_field` | [`String (Customer Sort Field)`](/doc/models/customer-sort-field.md) | Optional | Indicates the sort criteria for a list of Customers. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | - -### Example (as JSON) - -```json -{ - "cursor": null, - "sort_field": null, - "sort_order": null -} -``` - +## List Customers Request + +Defines the query parameters that can be provided in a request to the +ListCustomers endpoint. + +### Structure + +`ListCustomersRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `sort_field` | [`String (Customer Sort Field)`](/doc/models/customer-sort-field.md) | Optional | Indicates the sort criteria for a list of Customers. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | + +### Example (as JSON) + +```json +{ + "cursor": null, + "sort_field": null, + "sort_order": null +} +``` + diff --git a/doc/models/list-customers-response.md b/doc/models/list-customers-response.md index 124f45c6..e3446359 100644 --- a/doc/models/list-customers-response.md +++ b/doc/models/list-customers-response.md @@ -1,53 +1,53 @@ -## List Customers Response - -Defines the fields that are included in the response body of -a request to the ListCustomers endpoint. - -One of `errors` or `customers` is present in a given response (never both). - -### Structure - -`ListCustomersResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `customers` | [`Array`](/doc/models/customer.md) | Optional | An array of `Customer` objects that match your query. | -| `cursor` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. This value is present only if the request
succeeded and additional results are available.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "customers": [ - { - "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", - "created_at": "2016-03-23T20:21:54.859Z", - "updated_at": "2016-03-23T20:21:55Z", - "given_name": "Amelia", - "family_name": "Earhart", - "email_address": "Amelia.Earhart@example.com", - "address": { - "address_line_1": "500 Electric Ave", - "address_line_2": "Suite 600", - "locality": "New York", - "administrative_district_level_1": "NY", - "postal_code": "10003", - "country": "US" - }, - "phone_number": "1-212-555-4240", - "reference_id": "YOUR_REFERENCE_ID", - "note": "a customer", - "groups": [ - { - "id": "16894e93-96eb-4ced-b24b-f71d42bf084c", - "name": "Aviation Enthusiasts" - } - ] - } - ] -} -``` - +## List Customers Response + +Defines the fields that are included in the response body of +a request to the ListCustomers endpoint. + +One of `errors` or `customers` is present in a given response (never both). + +### Structure + +`ListCustomersResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `customers` | [`Array`](/doc/models/customer.md) | Optional | An array of `Customer` objects that match your query. | +| `cursor` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. This value is present only if the request
succeeded and additional results are available.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "customers": [ + { + "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", + "created_at": "2016-03-23T20:21:54.859Z", + "updated_at": "2016-03-23T20:21:55Z", + "given_name": "Amelia", + "family_name": "Earhart", + "email_address": "Amelia.Earhart@example.com", + "address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "locality": "New York", + "administrative_district_level_1": "NY", + "postal_code": "10003", + "country": "US" + }, + "phone_number": "1-212-555-4240", + "reference_id": "YOUR_REFERENCE_ID", + "note": "a customer", + "groups": [ + { + "id": "16894e93-96eb-4ced-b24b-f71d42bf084c", + "name": "Aviation Enthusiasts" + } + ] + } + ] +} +``` + diff --git a/doc/models/list-employee-wages-request.md b/doc/models/list-employee-wages-request.md index db9dc5d5..f4aff304 100644 --- a/doc/models/list-employee-wages-request.md +++ b/doc/models/list-employee-wages-request.md @@ -1,26 +1,26 @@ -## List Employee Wages Request - -A request for a set of `EmployeeWage` objects - -### Structure - -`ListEmployeeWagesRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `employee_id` | `String` | Optional | Filter wages returned to only those that are associated with the
specified employee. | -| `limit` | `Integer` | Optional | Maximum number of Employee Wages to return per page. Can range between
1 and 200. The default is the maximum at 200. | -| `cursor` | `String` | Optional | Pointer to the next page of Employee Wage results to fetch. | - -### Example (as JSON) - -```json -{ - "employee_id": null, - "limit": null, - "cursor": null -} -``` - +## List Employee Wages Request + +A request for a set of `EmployeeWage` objects + +### Structure + +`ListEmployeeWagesRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `employee_id` | `String` | Optional | Filter wages returned to only those that are associated with the
specified employee. | +| `limit` | `Integer` | Optional | Maximum number of Employee Wages to return per page. Can range between
1 and 200. The default is the maximum at 200. | +| `cursor` | `String` | Optional | Pointer to the next page of Employee Wage results to fetch. | + +### Example (as JSON) + +```json +{ + "employee_id": null, + "limit": null, + "cursor": null +} +``` + diff --git a/doc/models/list-employee-wages-response.md b/doc/models/list-employee-wages-response.md index aef66336..b17cb12d 100644 --- a/doc/models/list-employee-wages-response.md +++ b/doc/models/list-employee-wages-response.md @@ -1,63 +1,63 @@ -## List Employee Wages Response - -The response to a request for a set of `EmployeeWage` objects. Contains -a set of `EmployeeWage`. - -### Structure - -`ListEmployeeWagesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `employee_wages` | [`Array`](/doc/models/employee-wage.md) | Optional | A page of Employee Wage results. | -| `cursor` | `String` | Optional | Value supplied in the subsequent request to fetch the next next page
of Employee Wage results. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "employee_wages": [ - { - "id": "pXS3qCv7BERPnEGedM4S8mhm", - "employee_id": "33fJchumvVdJwxV0H6L9", - "title": "Manager", - "hourly_rate": { - "amount": 3250, - "currency": "USD" - } - }, - { - "id": "rZduCkzYDUVL3ovh1sQgbue6", - "employee_id": "33fJchumvVdJwxV0H6L9", - "title": "Cook", - "hourly_rate": { - "amount": 2600, - "currency": "USD" - } - }, - { - "id": "FxLbs5KpPUHa8wyt5ctjubDX", - "employee_id": "33fJchumvVdJwxV0H6L9", - "title": "Barista", - "hourly_rate": { - "amount": 1600, - "currency": "USD" - } - }, - { - "id": "vD1wCgijMDR3cX5TPnu7VXto", - "employee_id": "33fJchumvVdJwxV0H6L9", - "title": "Cashier", - "hourly_rate": { - "amount": 1700, - "currency": "USD" - } - } - ], - "cursor": "2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED" -} -``` - +## List Employee Wages Response + +The response to a request for a set of `EmployeeWage` objects. Contains +a set of `EmployeeWage`. + +### Structure + +`ListEmployeeWagesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `employee_wages` | [`Array`](/doc/models/employee-wage.md) | Optional | A page of Employee Wage results. | +| `cursor` | `String` | Optional | Value supplied in the subsequent request to fetch the next next page
of Employee Wage results. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "employee_wages": [ + { + "id": "pXS3qCv7BERPnEGedM4S8mhm", + "employee_id": "33fJchumvVdJwxV0H6L9", + "title": "Manager", + "hourly_rate": { + "amount": 3250, + "currency": "USD" + } + }, + { + "id": "rZduCkzYDUVL3ovh1sQgbue6", + "employee_id": "33fJchumvVdJwxV0H6L9", + "title": "Cook", + "hourly_rate": { + "amount": 2600, + "currency": "USD" + } + }, + { + "id": "FxLbs5KpPUHa8wyt5ctjubDX", + "employee_id": "33fJchumvVdJwxV0H6L9", + "title": "Barista", + "hourly_rate": { + "amount": 1600, + "currency": "USD" + } + }, + { + "id": "vD1wCgijMDR3cX5TPnu7VXto", + "employee_id": "33fJchumvVdJwxV0H6L9", + "title": "Cashier", + "hourly_rate": { + "amount": 1700, + "currency": "USD" + } + } + ], + "cursor": "2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED" +} +``` + diff --git a/doc/models/list-employees-request.md b/doc/models/list-employees-request.md index 9e11f1fa..8b7aecd1 100644 --- a/doc/models/list-employees-request.md +++ b/doc/models/list-employees-request.md @@ -1,28 +1,28 @@ -## List Employees Request - -Retrieve a paged-list of employees for a Square account - -### Structure - -`ListEmployeesRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Optional | Filter employees returned to only those that are associated with the
specified location. | -| `status` | [`String (Employee Status)`](/doc/models/employee-status.md) | Optional | The status of the Employee being retrieved. | -| `limit` | `Integer` | Optional | The number of employees to be returned on each page. | -| `cursor` | `String` | Optional | The token required to retrieve the specified page of results. | - -### Example (as JSON) - -```json -{ - "location_id": null, - "status": null, - "limit": null, - "cursor": null -} -``` - +## List Employees Request + +Retrieve a paged-list of employees for a Square account + +### Structure + +`ListEmployeesRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Optional | Filter employees returned to only those that are associated with the
specified location. | +| `status` | [`String (Employee Status)`](/doc/models/employee-status.md) | Optional | The status of the Employee being retrieved. | +| `limit` | `Integer` | Optional | The number of employees to be returned on each page. | +| `cursor` | `String` | Optional | The token required to retrieve the specified page of results. | + +### Example (as JSON) + +```json +{ + "location_id": null, + "status": null, + "limit": null, + "cursor": null +} +``` + diff --git a/doc/models/list-employees-response.md b/doc/models/list-employees-response.md index e42dc33a..ea4b56ed 100644 --- a/doc/models/list-employees-response.md +++ b/doc/models/list-employees-response.md @@ -1,29 +1,29 @@ -## List Employees Response - -Defines the fields that are included in the response body of -a request to the ListEmployees endpoint. - -One of `errors` or `employees` is present in a given response (never both). - -### Structure - -`ListEmployeesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `employees` | [`Array`](/doc/models/employee.md) | Optional | List of employees returned from the request. | -| `cursor` | `String` | Optional | The token to be used to retrieve the next page of results. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "employees": null, - "cursor": null, - "errors": null -} -``` - +## List Employees Response + +Defines the fields that are included in the response body of +a request to the ListEmployees endpoint. + +One of `errors` or `employees` is present in a given response (never both). + +### Structure + +`ListEmployeesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `employees` | [`Array`](/doc/models/employee.md) | Optional | List of employees returned from the request. | +| `cursor` | `String` | Optional | The token to be used to retrieve the next page of results. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "employees": null, + "cursor": null, + "errors": null +} +``` + diff --git a/doc/models/list-locations-response.md b/doc/models/list-locations-response.md index 6d23d363..fb0c484b 100644 --- a/doc/models/list-locations-response.md +++ b/doc/models/list-locations-response.md @@ -1,69 +1,50 @@ -## List Locations Response - -Defines the fields that are included in the response body of -a request to the ListLocations endpoint. - -One of `errors` or `locations` is present in a given response (never both). - -### Structure - -`ListLocationsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `locations` | [`Array`](/doc/models/location.md) | Optional | The business's locations. | - -### Example (as JSON) - -```json -{ - "locations": [ - { - "id": "18YC4JDH91E1H", - "name": "your location name", - "address": { - "address_line_1": "123 Main St", - "locality": "San Francisco", - "administrative_district_level_1": "CA", - "postal_code": "94114", - "country": "US" - }, - "timezone": "America/Los_Angeles", - "capabilities": [ - "CREDIT_CARD_PROCESSING" - ], - "status": "ACTIVE", - "created_at": "2016-09-19T17:33:12Z", - "merchant_id": "3MYCJG5GVYQ8Q", - "country": "US", - "language_code": "en-US", - "currency": "USD", - "phone_number": "+1 650-354-7217", - "business_name": "Pumbaa's business name", - "business_hours": { - "periods": [ - { - "day_of_week": "MON", - "start_local_time": "08:00:00", - "end_local_time": "17:00:00" - }, - { - "day_of_week": "TUE", - "start_local_time": "08:00:00", - "end_local_time": "17:00:00" - }, - { - "day_of_week": "WED", - "start_local_time": "08:00:00", - "end_local_time": "17:00:00" - } - ] - } - } - ] -} -``` - +## List Locations Response + +Defines the fields that are included in the response body of +a request to the ListLocations endpoint. + +One of `errors` or `locations` is present in a given response (never both). + +### Structure + +`ListLocationsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `locations` | [`Array`](/doc/models/location.md) | Optional | The business's locations. | + +### Example (as JSON) + +```json +{ + "locations": [ + { + "id": "18YC4JDH91E1H", + "name": "your location name", + "address": { + "address_line_1": "123 Main St", + "locality": "San Francisco", + "administrative_district_level_1": "CA", + "postal_code": "94114", + "country": "US" + }, + "timezone": "America/Los_Angeles", + "capabilities": [ + "CREDIT_CARD_PROCESSING" + ], + "status": "ACTIVE", + "created_at": "2016-09-19T17:33:12Z", + "merchant_id": "3MYCJG5GVYQ8Q", + "country": "US", + "language_code": "en-US", + "currency": "USD", + "phone_number": "+1 650-354-7217", + "business_name": "Pumbaa's business name" + } + ] +} +``` + diff --git a/doc/models/list-payment-refunds-request.md b/doc/models/list-payment-refunds-request.md index 0d0ca8df..b0a41625 100644 --- a/doc/models/list-payment-refunds-request.md +++ b/doc/models/list-payment-refunds-request.md @@ -1,36 +1,28 @@ -## List Payment Refunds Request - +## List Payment Refunds Request + Retrieves a list of refunds for the account making the request. -Max results per page: 100 - -### Structure - -`ListPaymentRefundsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `begin_time` | `String` | Optional | Timestamp for the beginning of the requested reporting period, in RFC 3339 format.

Default: The current time minus one year. | -| `end_time` | `String` | Optional | Timestamp for the end of the requested reporting period, in RFC 3339 format.

Default: The current time. | -| `sort_order` | `String` | Optional | The order in which results are listed.
- `ASC` - oldest to newest
- `DESC` - newest to oldest (default). | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `location_id` | `String` | Optional | ID of location associated with payment. | -| `status` | `String` | Optional | If provided, only refunds with the given status are returned.
For a list of refund status values, see [PaymentRefund](./models/payment-refund.md).

Default: If omitted refunds are returned regardless of status. | -| `source_type` | `String` | Optional | If provided, only refunds with the given source type are returned.
- `CARD` - List refunds only for payments where card was specified as payment
source.

Default: If omitted refunds are returned regardless of source type. | - -### Example (as JSON) - -```json -{ - "begin_time": null, - "end_time": null, - "sort_order": null, - "cursor": null, - "location_id": null, - "status": null, - "source_type": null -} -``` - +Max results per page: 100 + +### Structure + +`ListPaymentRefundsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `begin_time` | `String` | Optional | Timestamp for the beginning of the requested reporting period, in RFC 3339 format.

Default: The current time minus one year. | +| `end_time` | `String` | Optional | Timestamp for the end of the requested reporting period, in RFC 3339 format.

Default: The current time. | +| `sort_order` | `String` | Optional | The order in which results are listed.
- `ASC` - oldest to newest
- `DESC` - newest to oldest (default). | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `location_id` | `String` | Optional | ID of location associated with payment. | +| `status` | `String` | Optional | If provided, only refunds with the given status are returned.
For a list of refund status values, see [PaymentRefund](#type-paymentrefund).

Default: If omitted refunds are returned regardless of status. | +| `source_type` | `String` | Optional | If provided, only refunds with the given source type are returned.
- `CARD` - List refunds only for payments where card was specified as payment
source.

Default: If omitted refunds are returned regardless of source type. | + +### Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/list-payment-refunds-response.md b/doc/models/list-payment-refunds-response.md index db3db17b..49a06a30 100644 --- a/doc/models/list-payment-refunds-response.md +++ b/doc/models/list-payment-refunds-response.md @@ -1,29 +1,75 @@ -## List Payment Refunds Response - -Defines the fields that are included in the response body of -a request to the [ListPaymentRefunds](/doc/refunds.md#listpaymentrefunds) endpoint. - -One of `errors` or `refunds` is present in a given response (never both). - -### Structure - -`ListPaymentRefundsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `refunds` | [`Array`](/doc/models/payment-refund.md) | Optional | The list of requested refunds. | -| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If empty,
this is the final response.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "errors": null, - "refunds": null, - "cursor": null -} -``` - +## List Payment Refunds Response + +Defines the fields that are included in the response body of +a request to the [ListPaymentRefunds](#endpoint-refunds-listpaymentrefunds) endpoint. + +One of `errors` or `refunds` is present in a given response (never both). + +### Structure + +`ListPaymentRefundsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `refunds` | [`Array`](/doc/models/payment-refund.md) | Optional | The list of requested refunds. | +| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If empty,
this is the final response.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "refunds": [ + { + "id": "O2QAAhTYs7rUfzlxT38GMO7LvaB_q7JwCHtxmgXrh8fAhV468WQ44VxDtL7CU4yVRlsbXmI", + "created_at": "2019-07-06T18:01:22.335Z", + "updated_at": "2019-07-06T18:06:04.653Z", + "status": "COMPLETED", + "amount_money": { + "amount": 1000, + "currency": "USD" + }, + "payment_id": "O2QAAhTYs7rUfzlxT38GMO7LvaB", + "order_id": "2duiyoqbfeXY0DBi15GEyk5Epa4F", + "location_id": "XK3DBG77NJBFX", + "processing_fee": [ + { + "effective_at": "2019-07-06T20:01:12.000Z", + "type": "INITIAL", + "amount_money": { + "amount": -59, + "currency": "USD" + } + } + ] + }, + { + "id": "8TDIQvFw8PeDIxhSfd5yyX7GuaB_13px5Vrz01qzzuoGzmjsZIxDjfHhbkm2XppBUX1dW7I", + "created_at": "2019-07-06T17:01:54.232Z", + "updated_at": "2019-07-06T17:21:04.684Z", + "status": "COMPLETED", + "amount_money": { + "amount": 1000, + "currency": "USD" + }, + "payment_id": "8TDIQvFw8PeDIxhSfd5yyX7GuaB", + "order_id": "w6EXfEwS03oTQsnZTCqfE6f67e4F", + "processing_fee": [ + { + "effective_at": "2019-07-06T19:01:45.000Z", + "type": "INITIAL", + "amount_money": { + "amount": -59, + "currency": "USD" + } + } + ], + "location_id": "XK3DBG77NJBFX" + } + ], + "cursor": "5evquW1YswHoT4EoyUhzMmTsCnsSXBU9U0WJ4FU4623nrMQcocH0RGU6Up1YkwfiMcF59ood58EBTEGgzMTGHQJpocic7ExOL0NtrTXCeWcv0UJIJNk8eXb" +} +``` + diff --git a/doc/models/list-payments-request.md b/doc/models/list-payments-request.md index c29d755b..4265f429 100644 --- a/doc/models/list-payments-request.md +++ b/doc/models/list-payments-request.md @@ -1,29 +1,29 @@ -## List Payments Request - +## List Payments Request + Retrieves a list of refunds taken by the account making the request. -Max results per page: 100 - -### Structure - -`ListPaymentsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `begin_time` | `String` | Optional | Timestamp for the beginning of the reporting period, in RFC 3339 format.
Inclusive. Default: The current time minus one year. | -| `end_time` | `String` | Optional | Timestamp for the end of the requested reporting period, in RFC 3339 format.

Default: The current time. | -| `sort_order` | `String` | Optional | The order in which results are listed.
- `ASC` - oldest to newest
- `DESC` - newest to oldest (default). | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `location_id` | `String` | Optional | ID of location associated with payment | -| `total` | `Long` | Optional | The exact amount in the total_money for a `Payment`. | -| `last_4` | `String` | Optional | The last 4 digits of `Payment` card. | -| `card_brand` | `String` | Optional | The brand of `Payment` card. For example, `VISA` | - -### Example (as JSON) - -```json -{} -``` - +Max results per page: 100 + +### Structure + +`ListPaymentsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `begin_time` | `String` | Optional | Timestamp for the beginning of the reporting period, in RFC 3339 format.
Inclusive. Default: The current time minus one year. | +| `end_time` | `String` | Optional | Timestamp for the end of the requested reporting period, in RFC 3339 format.

Default: The current time. | +| `sort_order` | `String` | Optional | The order in which results are listed.
- `ASC` - oldest to newest
- `DESC` - newest to oldest (default). | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `location_id` | `String` | Optional | ID of location associated with payment | +| `total` | `Long` | Optional | The exact amount in the total_money for a `Payment`. | +| `last_4` | `String` | Optional | The last 4 digits of `Payment` card. | +| `card_brand` | `String` | Optional | The brand of `Payment` card. For example, `VISA` | + +### Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/list-payments-response.md b/doc/models/list-payments-response.md index 237731ef..6441da36 100644 --- a/doc/models/list-payments-response.md +++ b/doc/models/list-payments-response.md @@ -1,100 +1,100 @@ -## List Payments Response - -Defines the fields that are included in the response body of -a request to the [ListPayments](/doc/payments.md#listpayments) endpoint. - -### Structure - -`ListPaymentsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `payments` | [`Array`](/doc/models/payment.md) | Optional | The requested list of `Payment`s. | -| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If empty,
this is the final response.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "payments": [ - { - "id": "6SRrImjQGn8FuzIsURiN677CwaB", - "created_at": "2019-07-09T14:36:13.745Z", - "updated_at": "2019-07-09T14:36:13.883Z", - "amount_money": { - "amount": 1000, - "currency": "USD" - }, - "total_money": { - "amount": 1000, - "currency": "USD" - }, - "status": "APPROVED", - "source_type": "CARD", - "card_details": { - "status": "AUTHORIZED", - "card": { - "card_brand": "VISA", - "last_4": "1111", - "exp_month": 2, - "exp_year": 2022, - "fingerprint": "sq-1-lHpUJIUyqOPQmH89b6GuQEljmc-mZmu4kSTaMlkLDkJI7NVjAl4Zirn2sk3OeyVKVA" - }, - "entry_method": "KEYED", - "cvv_status": "CVV_ACCEPTED", - "avs_status": "AVS_ACCEPTED", - "auth_result_code": "NQbV3A" - }, - "location_id": "XK3DBG77NJBFX", - "order_id": "EM6qWxDd7RSy5udzjXktPw3PJa4F" - }, - { - "id": "MRWmTKxBDNRgwfNSZptAO76xuaB", - "created_at": "2019-07-08T01:00:51.607Z", - "updated_at": "2019-07-08T01:13:58.508Z", - "amount_money": { - "amount": 1000, - "currency": "USD" - }, - "total_money": { - "amount": 1000, - "currency": "USD" - }, - "status": "COMPLETED", - "source_type": "CARD", - "card_details": { - "status": "CAPTURED", - "card": { - "card_brand": "VISA", - "last_4": "2796", - "exp_month": 7, - "exp_year": 2026, - "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw" - }, - "entry_method": "ON_FILE", - "cvv_status": "CVV_ACCEPTED", - "avs_status": "AVS_ACCEPTED", - "auth_result_code": "vPIr0K" - }, - "location_id": "XK3DBG77NJBFX", - "order_id": "OVE4bJyb4B6bGFwMYEtVdfE4ge4F", - "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8", - "processing_fee": [ - { - "effective_at": "2019-07-08T03:00:53.000Z", - "type": "INITIAL", - "amount_money": { - "amount": 59, - "currency": "USD" - } - } - ] - } - ], - "cursor": "Q2g4SUF4SWJUVkpYYlZSTGVFSkVUbEpuZDJaT1UxcHdkRUZQTnpaNGRXRkNFSmVJNVBpOExRPT0" -} -``` - +## List Payments Response + +Defines the fields that are included in the response body of +a request to the [ListPayments](#endpoint-payments-listpayments) endpoint. + +### Structure + +`ListPaymentsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `payments` | [`Array`](/doc/models/payment.md) | Optional | The requested list of `Payment`s. | +| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If empty,
this is the final response.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "payments": [ + { + "id": "6SRrImjQGn8FuzIsURiN677CwaB", + "created_at": "2019-07-09T14:36:13.745Z", + "updated_at": "2019-07-09T14:36:13.883Z", + "amount_money": { + "amount": 1000, + "currency": "USD" + }, + "total_money": { + "amount": 1000, + "currency": "USD" + }, + "status": "APPROVED", + "source_type": "CARD", + "card_details": { + "status": "AUTHORIZED", + "card": { + "card_brand": "VISA", + "last_4": "1111", + "exp_month": 2, + "exp_year": 2022, + "fingerprint": "sq-1-lHpUJIUyqOPQmH89b6GuQEljmc-mZmu4kSTaMlkLDkJI7NVjAl4Zirn2sk3OeyVKVA" + }, + "entry_method": "KEYED", + "cvv_status": "CVV_ACCEPTED", + "avs_status": "AVS_ACCEPTED", + "auth_result_code": "NQbV3A" + }, + "location_id": "XK3DBG77NJBFX", + "order_id": "EM6qWxDd7RSy5udzjXktPw3PJa4F" + }, + { + "id": "MRWmTKxBDNRgwfNSZptAO76xuaB", + "created_at": "2019-07-08T01:00:51.607Z", + "updated_at": "2019-07-08T01:13:58.508Z", + "amount_money": { + "amount": 1000, + "currency": "USD" + }, + "total_money": { + "amount": 1000, + "currency": "USD" + }, + "status": "COMPLETED", + "source_type": "CARD", + "card_details": { + "status": "CAPTURED", + "card": { + "card_brand": "VISA", + "last_4": "2796", + "exp_month": 7, + "exp_year": 2026, + "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw" + }, + "entry_method": "ON_FILE", + "cvv_status": "CVV_ACCEPTED", + "avs_status": "AVS_ACCEPTED", + "auth_result_code": "vPIr0K" + }, + "location_id": "XK3DBG77NJBFX", + "order_id": "OVE4bJyb4B6bGFwMYEtVdfE4ge4F", + "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8", + "processing_fee": [ + { + "effective_at": "2019-07-08T03:00:53.000Z", + "type": "INITIAL", + "amount_money": { + "amount": 59, + "currency": "USD" + } + } + ] + } + ], + "cursor": "Q2g4SUF4SWJUVkpYYlZSTGVFSkVUbEpuZDJaT1UxcHdkRUZQTnpaNGRXRkNFSmVJNVBpOExRPT0" +} +``` + diff --git a/doc/models/list-refunds-request.md b/doc/models/list-refunds-request.md index 0c1572ca..ad1ae051 100644 --- a/doc/models/list-refunds-request.md +++ b/doc/models/list-refunds-request.md @@ -1,31 +1,31 @@ -## List Refunds Request - -Defines the query parameters that can be included in -a request to the [ListRefunds](#endpoint-listrefunds) endpoint. - -Deprecated - recommend using [SearchOrders](/doc/orders.md#searchorders) - -### Structure - -`ListRefundsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | -| `end_time` | `String` | Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "begin_time": null, - "end_time": null, - "sort_order": null, - "cursor": null -} -``` - +## List Refunds Request + +Defines the query parameters that can be included in +a request to the [ListRefunds](#endpoint-listrefunds) endpoint. + +Deprecated - recommend using [SearchOrders](#endpoint-orders-searchorders) + +### Structure + +`ListRefundsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | +| `end_time` | `String` | Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "begin_time": null, + "end_time": null, + "sort_order": null, + "cursor": null +} +``` + diff --git a/doc/models/list-refunds-response.md b/doc/models/list-refunds-response.md index ec83386f..228166bb 100644 --- a/doc/models/list-refunds-response.md +++ b/doc/models/list-refunds-response.md @@ -1,51 +1,51 @@ -## List Refunds Response - -Defines the fields that are included in the response body of -a request to the [ListRefunds](#endpoint-listrefunds) endpoint. - -One of `errors` or `refunds` is present in a given response (never both). - -### Structure - -`ListRefundsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `refunds` | [`Array`](/doc/models/refund.md) | Optional | An array of refunds that match your query. | -| `cursor` | `String` | Optional | A pagination cursor for retrieving the next set of results,
if any remain. Provide this value as the `cursor` parameter in a subsequent
request to this endpoint.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "refunds": [ - { - "id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW", - "location_id": "18YC4JDH91E1H", - "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", - "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF", - "created_at": "2016-01-20T00:28:18Z", - "reason": "some reason", - "amount_money": { - "amount": 100, - "currency": "USD" - }, - "additional_recipients": [ - { - "location_id": "057P5VYJ4A5X1", - "description": "Application fees", - "amount_money": { - "amount": 10, - "currency": "USD" - } - } - ], - "status": "APPROVED" - } - ] -} -``` - +## List Refunds Response + +Defines the fields that are included in the response body of +a request to the [ListRefunds](#endpoint-listrefunds) endpoint. + +One of `errors` or `refunds` is present in a given response (never both). + +### Structure + +`ListRefundsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `refunds` | [`Array`](/doc/models/refund.md) | Optional | An array of refunds that match your query. | +| `cursor` | `String` | Optional | A pagination cursor for retrieving the next set of results,
if any remain. Provide this value as the `cursor` parameter in a subsequent
request to this endpoint.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "refunds": [ + { + "id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW", + "location_id": "18YC4JDH91E1H", + "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", + "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF", + "created_at": "2016-01-20T00:28:18Z", + "reason": "some reason", + "amount_money": { + "amount": 100, + "currency": "USD" + }, + "additional_recipients": [ + { + "location_id": "057P5VYJ4A5X1", + "description": "Application fees", + "amount_money": { + "amount": 10, + "currency": "USD" + } + } + ], + "status": "APPROVED" + } + ] +} +``` + diff --git a/doc/models/list-transactions-request.md b/doc/models/list-transactions-request.md index 3f656d41..d0241c50 100644 --- a/doc/models/list-transactions-request.md +++ b/doc/models/list-transactions-request.md @@ -1,31 +1,31 @@ -## List Transactions Request - -Defines the query parameters that can be included in -a request to the [ListTransactions](#endpoint-listtransactions) endpoint. - -Deprecated - recommend using [SearchOrders](/doc/orders.md#searchorders) - -### Structure - -`ListTransactionsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | -| `end_time` | `String` | Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "begin_time": null, - "end_time": null, - "sort_order": null, - "cursor": null -} -``` - +## List Transactions Request + +Defines the query parameters that can be included in +a request to the [ListTransactions](#endpoint-listtransactions) endpoint. + +Deprecated - recommend using [SearchOrders](#endpoint-orders-searchorders) + +### Structure + +`ListTransactionsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | +| `end_time` | `String` | Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "begin_time": null, + "end_time": null, + "sort_order": null, + "cursor": null +} +``` + diff --git a/doc/models/list-transactions-response.md b/doc/models/list-transactions-response.md index 52058050..1cdf863f 100644 --- a/doc/models/list-transactions-response.md +++ b/doc/models/list-transactions-response.md @@ -1,100 +1,100 @@ -## List Transactions Response - -Defines the fields that are included in the response body of -a request to the [ListTransactions](#endpoint-listtransactions) endpoint. - -One of `errors` or `transactions` is present in a given response (never both). - -### Structure - -`ListTransactionsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `transactions` | [`Array`](/doc/models/transaction.md) | Optional | An array of transactions that match your query. | -| `cursor` | `String` | Optional | A pagination cursor for retrieving the next set of results,
if any remain. Provide this value as the `cursor` parameter in a subsequent
request to this endpoint.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "transactions": [ - { - "id": "KnL67ZIwXCPtzOrqj0HrkxMF", - "location_id": "18YC4JDH91E1H", - "created_at": "2016-01-20T22:57:56Z", - "tenders": [ - { - "id": "MtZRYYdDrYNQbOvV7nbuBvMF", - "location_id": "18YC4JDH91E1H", - "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", - "created_at": "2016-01-20T22:57:56Z", - "note": "some optional note", - "amount_money": { - "amount": 5000, - "currency": "USD" - }, - "processing_fee_money": { - "amount": 138, - "currency": "USD" - }, - "type": "CARD", - "card_details": { - "status": "CAPTURED", - "card": { - "card_brand": "VISA", - "last_4": "1111" - }, - "entry_method": "KEYED" - }, - "additional_recipients": [ - { - "location_id": "057P5VYJ4A5X1", - "description": "Application fees", - "amount_money": { - "amount": 20, - "currency": "USD" - } - } - ] - } - ], - "refunds": [ - { - "id": "7a5RcVI0CxbOcJ2wMOkE", - "location_id": "18YC4JDH91E1H", - "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", - "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF", - "created_at": "2016-01-20T22:59:20Z", - "reason": "some reason why", - "amount_money": { - "amount": 5000, - "currency": "USD" - }, - "status": "APPROVED", - "processing_fee_money": { - "amount": 138, - "currency": "USD" - }, - "additional_recipients": [ - { - "location_id": "057P5VYJ4A5X1", - "description": "Application fees", - "amount_money": { - "amount": 100, - "currency": "USD" - } - } - ] - } - ], - "reference_id": "some optional reference id", - "product": "EXTERNAL_API" - } - ] -} -``` - +## List Transactions Response + +Defines the fields that are included in the response body of +a request to the [ListTransactions](#endpoint-listtransactions) endpoint. + +One of `errors` or `transactions` is present in a given response (never both). + +### Structure + +`ListTransactionsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `transactions` | [`Array`](/doc/models/transaction.md) | Optional | An array of transactions that match your query. | +| `cursor` | `String` | Optional | A pagination cursor for retrieving the next set of results,
if any remain. Provide this value as the `cursor` parameter in a subsequent
request to this endpoint.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "transactions": [ + { + "id": "KnL67ZIwXCPtzOrqj0HrkxMF", + "location_id": "18YC4JDH91E1H", + "created_at": "2016-01-20T22:57:56Z", + "tenders": [ + { + "id": "MtZRYYdDrYNQbOvV7nbuBvMF", + "location_id": "18YC4JDH91E1H", + "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", + "created_at": "2016-01-20T22:57:56Z", + "note": "some optional note", + "amount_money": { + "amount": 5000, + "currency": "USD" + }, + "processing_fee_money": { + "amount": 138, + "currency": "USD" + }, + "type": "CARD", + "card_details": { + "status": "CAPTURED", + "card": { + "card_brand": "VISA", + "last_4": "1111" + }, + "entry_method": "KEYED" + }, + "additional_recipients": [ + { + "location_id": "057P5VYJ4A5X1", + "description": "Application fees", + "amount_money": { + "amount": 20, + "currency": "USD" + } + } + ] + } + ], + "refunds": [ + { + "id": "7a5RcVI0CxbOcJ2wMOkE", + "location_id": "18YC4JDH91E1H", + "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", + "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF", + "created_at": "2016-01-20T22:59:20Z", + "reason": "some reason why", + "amount_money": { + "amount": 5000, + "currency": "USD" + }, + "status": "APPROVED", + "processing_fee_money": { + "amount": 138, + "currency": "USD" + }, + "additional_recipients": [ + { + "location_id": "057P5VYJ4A5X1", + "description": "Application fees", + "amount_money": { + "amount": 100, + "currency": "USD" + } + } + ] + } + ], + "reference_id": "some optional reference id", + "product": "EXTERNAL_API" + } + ] +} +``` + diff --git a/doc/models/list-workweek-configs-request.md b/doc/models/list-workweek-configs-request.md index 7ed2c66c..4f80a89b 100644 --- a/doc/models/list-workweek-configs-request.md +++ b/doc/models/list-workweek-configs-request.md @@ -1,24 +1,24 @@ -## List Workweek Configs Request - -A request for a set of `WorkweekConfig` objects - -### Structure - -`ListWorkweekConfigsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `limit` | `Integer` | Optional | Maximum number of Workweek Configs to return per page. | -| `cursor` | `String` | Optional | Pointer to the next page of Workweek Config results to fetch. | - -### Example (as JSON) - -```json -{ - "limit": null, - "cursor": null -} -``` - +## List Workweek Configs Request + +A request for a set of `WorkweekConfig` objects + +### Structure + +`ListWorkweekConfigsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `limit` | `Integer` | Optional | Maximum number of Workweek Configs to return per page. | +| `cursor` | `String` | Optional | Pointer to the next page of Workweek Config results to fetch. | + +### Example (as JSON) + +```json +{ + "limit": null, + "cursor": null +} +``` + diff --git a/doc/models/list-workweek-configs-response.md b/doc/models/list-workweek-configs-response.md index ed26aec3..e9114e8d 100644 --- a/doc/models/list-workweek-configs-response.md +++ b/doc/models/list-workweek-configs-response.md @@ -1,36 +1,36 @@ -## List Workweek Configs Response - -The response to a request for a set of `WorkweekConfig` objects. Contains -the requested `WorkweekConfig` objects. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`ListWorkweekConfigsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `workweek_configs` | [`Array`](/doc/models/workweek-config.md) | Optional | A page of Employee Wage results. | -| `cursor` | `String` | Optional | Value supplied in the subsequent request to fetch the next page of
Employee Wage results. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "workweek_configs": [ - { - "id": "FY4VCAQN700GM", - "start_of_week": "MON", - "start_of_day_local_time": "10:00", - "version": 11, - "created_at": "2016-02-04T00:58:24Z", - "updated_at": "2019-02-28T01:04:35Z" - } - ], - "cursor": "2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED" -} -``` - +## List Workweek Configs Response + +The response to a request for a set of `WorkweekConfig` objects. Contains +the requested `WorkweekConfig` objects. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`ListWorkweekConfigsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `workweek_configs` | [`Array`](/doc/models/workweek-config.md) | Optional | A page of Employee Wage results. | +| `cursor` | `String` | Optional | Value supplied in the subsequent request to fetch the next page of
Employee Wage results. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "workweek_configs": [ + { + "id": "FY4VCAQN700GM", + "start_of_week": "MON", + "start_of_day_local_time": "10:00", + "version": 11, + "created_at": "2016-02-04T00:58:24Z", + "updated_at": "2019-02-28T01:04:35Z" + } + ], + "cursor": "2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED" +} +``` + diff --git a/doc/models/location-capability.md b/doc/models/location-capability.md index 01fbaf05..97555e5f 100644 --- a/doc/models/location-capability.md +++ b/doc/models/location-capability.md @@ -1,15 +1,15 @@ -## Location Capability - +## Location Capability + Indicates payment capabilities that a business's location might or -might not have enabled. - -### Enumeration - -`LocationCapability` - -### Fields - -| Name | Description | -| --- | --- | -| `CREDIT_CARD_PROCESSING` | The location can process credit cards with Square.

If this value is not present in a [`Location`](#type-location)'s'
`capabilities` array, the location _cannot_ process credit cards. | - +might not have enabled. + +### Enumeration + +`LocationCapability` + +### Fields + +| Name | Description | +| --- | --- | +| `CREDIT_CARD_PROCESSING` | The location can process credit cards with Square.

If this value is not present in a [`Location`](#type-location)'s'
`capabilities` array, the location _cannot_ process credit cards. | + diff --git a/doc/models/location-status.md b/doc/models/location-status.md index dd5da976..d8b3b4ab 100644 --- a/doc/models/location-status.md +++ b/doc/models/location-status.md @@ -1,15 +1,15 @@ -## Location Status - -Indicates the location's status. - -### Enumeration - -`LocationStatus` - -### Fields - -| Name | Description | -| --- | --- | -| `ACTIVE` | A fully operational location. The location can be used across all Square products and APIs. | -| `INACTIVE` | A functionally limited location. The location can only be used via Square APIs.

__NOTE__: We __strongly__ discourage the use of inactive locations.
Making API calls with inactive locations will cause complications
if the restrictions on inactive locations increase in the future. | - +## Location Status + +Indicates the location's status. + +### Enumeration + +`LocationStatus` + +### Fields + +| Name | Description | +| --- | --- | +| `ACTIVE` | A fully operational location. The location can be used across all Square products and APIs. | +| `INACTIVE` | A functionally limited location. The location can only be used via Square APIs.

__NOTE__: We __strongly__ discourage the use of inactive locations.
Making API calls with inactive locations will cause complications
if the restrictions on inactive locations increase in the future. | + diff --git a/doc/models/location-type.md b/doc/models/location-type.md index c1fca0c8..1c50e723 100644 --- a/doc/models/location-type.md +++ b/doc/models/location-type.md @@ -1,15 +1,15 @@ -## Location Type - -Indicates the location's type. - -### Enumeration - -`LocationType` - -### Fields - -| Name | Description | -| --- | --- | -| `PHYSICAL` | A physical location of a business. | -| `MOBILE` | A location without a physical address. For example: mobile food truck, online store, phone app. | - +## Location Type + +Indicates the location's type. + +### Enumeration + +`LocationType` + +### Fields + +| Name | Description | +| --- | --- | +| `PHYSICAL` | A physical location of a business. | +| `MOBILE` | A location without a physical address. For example: mobile food truck, online store, phone app. | + diff --git a/doc/models/location.md b/doc/models/location.md index dd17b579..d9f3fea1 100644 --- a/doc/models/location.md +++ b/doc/models/location.md @@ -1,64 +1,70 @@ -## Location - -Represents one of a business's locations. - -### Structure - -`Location` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The location's unique ID. | -| `name` | `String` | Optional | The location's name. Location names are set by the account owner and displayed
in the dashboard as the location's nickname | -| `address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `timezone` | `String` | Optional | The [IANA Timezone Database](https://www.iana.org/time-zones)
identifier for the location's timezone. | -| `capabilities` | [`Array`](/doc/models/location-capability.md) | Optional | Indicates which Square features are enabled for the location.
See [LocationCapability](./models/location-capability.md) for possible values | -| `status` | [`String (Location Status)`](/doc/models/location-status.md) | Optional | Indicates the location's status. | -| `created_at` | `String` | Optional | The time when the location was created, in RFC 3339 format. | -| `merchant_id` | `String` | Optional | The identifier of the merchant that owns the location. | -| `country` | [`String (Country)`](/doc/models/country.md) | Optional | Indicates the country associated with another entity, such as a business.
Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). | -| `language_code` | `String` | Optional | The language associated with the location in
[BCP 47 format](https://tools.ietf.org/html/bcp47#appendix-A). | -| `currency` | [`String (Currency)`](/doc/models/currency.md) | Optional | Indicates the associated currency for an amount of money. Values correspond
to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). | -| `phone_number` | `String` | Optional | The location's phone_number. | -| `business_name` | `String` | Optional | The location's business_name which is shown to its customers. For example,
this is the name printed on its customer's receipts. | -| `type` | [`String (Location Type)`](/doc/models/location-type.md) | Optional | Indicates the location's type. | -| `website_url` | `String` | Optional | The location's website, as set by the account owner in the Square dashboard.

Default: none; only exists if explicitly set. | -| `business_hours` | [`Business Hours Hash`](/doc/models/business-hours.md) | Optional | Represents the hours of operation for a business location. | -| `business_email` | `String` | Optional | The email of the location. | -| `description` | `String` | Optional | The business description of the location. | -| `twitter_username` | `String` | Optional | The Twitter username of the location without the ' | -| `instagram_username` | `String` | Optional | The Instagram username of the location without the ' | -| `facebook_url` | `String` | Optional | The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. | -| `coordinates` | [`Coordinates Hash`](/doc/models/coordinates.md) | Optional | Latitude and longitude coordinates. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null, - "address": null, - "timezone": null, - "capabilities": null, - "status": null, - "created_at": null, - "merchant_id": null, - "country": null, - "language_code": null, - "currency": null, - "phone_number": null, - "business_name": null, - "type": null, - "website_url": null, - "business_hours": null, - "business_email": null, - "description": null, - "twitter_username": null, - "instagram_username": null, - "facebook_url": null, - "coordinates": null -} -``` - +## Location + +Represents one of a business's locations. + +### Structure + +`Location` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The location's unique ID. | +| `name` | `String` | Optional | The location's name. Location names are set by the account owner and displayed
in the dashboard as the location's nickname | +| `address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `timezone` | `String` | Optional | The [IANA Timezone Database](https://www.iana.org/time-zones)
identifier for the location's timezone. | +| `capabilities` | [`Array`](/doc/models/location-capability.md) | Optional | Indicates which Square features are enabled for the location.
See [LocationCapability](#type-locationcapability) for possible values | +| `status` | [`String (Location Status)`](/doc/models/location-status.md) | Optional | Indicates the location's status. | +| `created_at` | `String` | Optional | The time when the location was created, in RFC 3339 format. | +| `merchant_id` | `String` | Optional | The identifier of the merchant that owns the location. | +| `country` | [`String (Country)`](/doc/models/country.md) | Optional | Indicates the country associated with another entity, such as a business.
Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). | +| `language_code` | `String` | Optional | The language associated with the location in
[BCP 47 format](https://tools.ietf.org/html/bcp47#appendix-A). | +| `currency` | [`String (Currency)`](/doc/models/currency.md) | Optional | Indicates the associated currency for an amount of money. Values correspond
to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). | +| `phone_number` | `String` | Optional | The location's phone_number. | +| `business_name` | `String` | Optional | The location's business_name which is shown to its customers. For example,
this is the name printed on its customer's receipts. | +| `type` | [`String (Location Type)`](/doc/models/location-type.md) | Optional | Indicates the location's type. | +| `website_url` | `String` | Optional | The location's website, as set by the account owner in the Square dashboard.

Default: none; only exists if explicitly set. | +| `business_hours` | [`Business Hours Hash`](/doc/models/business-hours.md) | Optional | Represents the hours of operation for a business location. | +| `business_email` | `String` | Optional | The email of the location. | +| `description` | `String` | Optional | The business description of the location. | +| `twitter_username` | `String` | Optional | The Twitter username of the location without the '@' symbol. | +| `instagram_username` | `String` | Optional | The Instagram username of the location without the '@' symbol. | +| `facebook_url` | `String` | Optional | The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. | +| `coordinates` | [`Coordinates Hash`](/doc/models/coordinates.md) | Optional | Latitude and longitude coordinates. | +| `logo_url` | `String` | Optional | The logo image URL of the location. | +| `pos_background_url` | `String` | Optional | The Point of Sale background image URL of the location. | +| `mcc` | `String` | Optional | The merchant category code (MCC) of the location, as standardized by ISO 18245.
The MCC describes the kind of goods or services sold at the location. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null, + "address": null, + "timezone": null, + "capabilities": null, + "status": null, + "created_at": null, + "merchant_id": null, + "country": null, + "language_code": null, + "currency": null, + "phone_number": null, + "business_name": null, + "type": null, + "website_url": null, + "business_hours": null, + "business_email": null, + "description": null, + "twitter_username": null, + "instagram_username": null, + "facebook_url": null, + "coordinates": null, + "logo_url": null, + "pos_background_url": null, + "mcc": null +} +``` + diff --git a/doc/models/measurement-unit-area.md b/doc/models/measurement-unit-area.md index 81b9ac47..6500f959 100644 --- a/doc/models/measurement-unit-area.md +++ b/doc/models/measurement-unit-area.md @@ -1,21 +1,21 @@ -## Measurement Unit Area - -Unit of area used to measure a quantity. - -### Enumeration - -`MeasurementUnitArea` - -### Fields - -| Name | Description | -| --- | --- | -| `IMPERIAL_ACRE` | The area is measured in acres. | -| `IMPERIAL_SQUARE_INCH` | The area is measured in square inches. | -| `IMPERIAL_SQUARE_FOOT` | The area is measured in square feet. | -| `IMPERIAL_SQUARE_YARD` | The area is measured in square yards. | -| `IMPERIAL_SQUARE_MILE` | The area is measured in square miles. | -| `METRIC_SQUARE_CENTIMETER` | The area is measured in square centimeters. | -| `METRIC_SQUARE_METER` | The area is measured in square meters. | -| `METRIC_SQUARE_KILOMETER` | The area is measured in square kilometers. | - +## Measurement Unit Area + +Unit of area used to measure a quantity. + +### Enumeration + +`MeasurementUnitArea` + +### Fields + +| Name | Description | +| --- | --- | +| `IMPERIAL_ACRE` | The area is measured in acres. | +| `IMPERIAL_SQUARE_INCH` | The area is measured in square inches. | +| `IMPERIAL_SQUARE_FOOT` | The area is measured in square feet. | +| `IMPERIAL_SQUARE_YARD` | The area is measured in square yards. | +| `IMPERIAL_SQUARE_MILE` | The area is measured in square miles. | +| `METRIC_SQUARE_CENTIMETER` | The area is measured in square centimeters. | +| `METRIC_SQUARE_METER` | The area is measured in square meters. | +| `METRIC_SQUARE_KILOMETER` | The area is measured in square kilometers. | + diff --git a/doc/models/measurement-unit-custom.md b/doc/models/measurement-unit-custom.md index 14b01ac4..3461f508 100644 --- a/doc/models/measurement-unit-custom.md +++ b/doc/models/measurement-unit-custom.md @@ -1,24 +1,24 @@ -## Measurement Unit Custom - -The information needed to define a custom unit, provided by the seller. - -### Structure - -`MeasurementUnitCustom` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `name` | `String` | The name of the custom unit, for example "bushel". | -| `abbreviation` | `String` | The abbreviation of the custom unit, such as "bsh" (bushel). This appears
in the cart for the Point of Sale app, and in reports. | - -### Example (as JSON) - -```json -{ - "name": "name0", - "abbreviation": "abbreviation2" -} -``` - +## Measurement Unit Custom + +The information needed to define a custom unit, provided by the seller. + +### Structure + +`MeasurementUnitCustom` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `name` | `String` | The name of the custom unit, for example "bushel". | +| `abbreviation` | `String` | The abbreviation of the custom unit, such as "bsh" (bushel). This appears
in the cart for the Point of Sale app, and in reports. | + +### Example (as JSON) + +```json +{ + "name": "name0", + "abbreviation": "abbreviation2" +} +``` + diff --git a/doc/models/measurement-unit-generic.md b/doc/models/measurement-unit-generic.md index 0de507a2..ca53b4f7 100644 --- a/doc/models/measurement-unit-generic.md +++ b/doc/models/measurement-unit-generic.md @@ -1,15 +1,14 @@ -## Measurement Unit Generic - -A custom unit of measurement defined by the user. - -### Enumeration - -`MeasurementUnitGeneric` - -### Fields - -| Name | Description | -| --- | --- | -| `INVALID_GENERIC_UNIT` | - | -| `UNIT` | - | - +## Measurement Unit Generic + +A custom unit of measurement defined by the user. + +### Enumeration + +`MeasurementUnitGeneric` + +### Fields + +| Name | Description | +| --- | --- | +| `UNIT` | - | + diff --git a/doc/models/measurement-unit-length.md b/doc/models/measurement-unit-length.md index 8ef03e79..87f18162 100644 --- a/doc/models/measurement-unit-length.md +++ b/doc/models/measurement-unit-length.md @@ -1,21 +1,21 @@ -## Measurement Unit Length - -The unit of length used to measure a quantity. - -### Enumeration - -`MeasurementUnitLength` - -### Fields - -| Name | Description | -| --- | --- | -| `IMPERIAL_INCH` | The length is measured in inches. | -| `IMPERIAL_FOOT` | The length is measured in feet. | -| `IMPERIAL_YARD` | The length is measured in yards. | -| `IMPERIAL_MILE` | The length is measured in miles. | -| `METRIC_MILLIMETER` | The length is measured in millimeters. | -| `METRIC_CENTIMETER` | The length is measured in centimeters. | -| `METRIC_METER` | The length is measured in meters. | -| `METRIC_KILOMETER` | The length is measured in kilometers. | - +## Measurement Unit Length + +The unit of length used to measure a quantity. + +### Enumeration + +`MeasurementUnitLength` + +### Fields + +| Name | Description | +| --- | --- | +| `IMPERIAL_INCH` | The length is measured in inches. | +| `IMPERIAL_FOOT` | The length is measured in feet. | +| `IMPERIAL_YARD` | The length is measured in yards. | +| `IMPERIAL_MILE` | The length is measured in miles. | +| `METRIC_MILLIMETER` | The length is measured in millimeters. | +| `METRIC_CENTIMETER` | The length is measured in centimeters. | +| `METRIC_METER` | The length is measured in meters. | +| `METRIC_KILOMETER` | The length is measured in kilometers. | + diff --git a/doc/models/measurement-unit-time.md b/doc/models/measurement-unit-time.md new file mode 100644 index 00000000..e86af645 --- /dev/null +++ b/doc/models/measurement-unit-time.md @@ -0,0 +1,18 @@ +## Measurement Unit Time + +Unit of time used to measure a quantity (a duration). + +### Enumeration + +`MeasurementUnitTime` + +### Fields + +| Name | Description | +| --- | --- | +| `GENERIC_MILLISECOND` | The time is measured in milliseconds. | +| `GENERIC_SECOND` | The time is measured in seconds. | +| `GENERIC_MINUTE` | The time is measured in minutes. | +| `GENERIC_HOUR` | The time is measured in hours. | +| `GENERIC_DAY` | The time is measured in days. | + diff --git a/doc/models/measurement-unit-unit-type.md b/doc/models/measurement-unit-unit-type.md new file mode 100644 index 00000000..4a7527ff --- /dev/null +++ b/doc/models/measurement-unit-unit-type.md @@ -0,0 +1,19 @@ +## Measurement Unit Unit Type + +Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum. + +### Enumeration + +`MeasurementUnitUnitType` + +### Fields + +| Name | Description | +| --- | --- | +| `TYPE_CUSTOM` | The unit details are contained in the custom_unit field. | +| `TYPE_AREA` | The unit details are contained in the area_unit field. | +| `TYPE_LENGTH` | The unit details are contained in the length_unit field. | +| `TYPE_VOLUME` | The unit details are contained in the volume_unit field. | +| `TYPE_WEIGHT` | The unit details are contained in the weight_unit field. | +| `TYPE_GENERIC` | The unit details are contained in the generic_unit field. | + diff --git a/doc/models/measurement-unit-volume.md b/doc/models/measurement-unit-volume.md index e1867d75..27232989 100644 --- a/doc/models/measurement-unit-volume.md +++ b/doc/models/measurement-unit-volume.md @@ -1,24 +1,24 @@ -## Measurement Unit Volume - -The unit of volume used to measure a quantity. - -### Enumeration - -`MeasurementUnitVolume` - -### Fields - -| Name | Description | -| --- | --- | -| `GENERIC_FLUID_OUNCE` | The volume is measured in ounces. | -| `GENERIC_SHOT` | The volume is measured in shots. | -| `GENERIC_CUP` | The volume is measured in cups. | -| `GENERIC_PINT` | The volume is measured in pints. | -| `GENERIC_QUART` | The volume is measured in quarts. | -| `GENERIC_GALLON` | The volume is measured in gallons. | -| `IMPERIAL_CUBIC_INCH` | The volume is measured in cubic inches. | -| `IMPERIAL_CUBIC_FOOT` | The volume is measured in cubic feet. | -| `IMPERIAL_CUBIC_YARD` | The volume is measured in cubic yards. | -| `METRIC_MILLILITER` | The volume is measured in metric milliliters. | -| `METRIC_LITER` | The volume is measured in metric liters. | - +## Measurement Unit Volume + +The unit of volume used to measure a quantity. + +### Enumeration + +`MeasurementUnitVolume` + +### Fields + +| Name | Description | +| --- | --- | +| `GENERIC_FLUID_OUNCE` | The volume is measured in ounces. | +| `GENERIC_SHOT` | The volume is measured in shots. | +| `GENERIC_CUP` | The volume is measured in cups. | +| `GENERIC_PINT` | The volume is measured in pints. | +| `GENERIC_QUART` | The volume is measured in quarts. | +| `GENERIC_GALLON` | The volume is measured in gallons. | +| `IMPERIAL_CUBIC_INCH` | The volume is measured in cubic inches. | +| `IMPERIAL_CUBIC_FOOT` | The volume is measured in cubic feet. | +| `IMPERIAL_CUBIC_YARD` | The volume is measured in cubic yards. | +| `METRIC_MILLILITER` | The volume is measured in metric milliliters. | +| `METRIC_LITER` | The volume is measured in metric liters. | + diff --git a/doc/models/measurement-unit-weight.md b/doc/models/measurement-unit-weight.md index 93a93ad1..1e3f1eee 100644 --- a/doc/models/measurement-unit-weight.md +++ b/doc/models/measurement-unit-weight.md @@ -1,19 +1,19 @@ -## Measurement Unit Weight - -Unit of weight used to measure a quantity. - -### Enumeration - -`MeasurementUnitWeight` - -### Fields - -| Name | Description | -| --- | --- | -| `IMPERIAL_WEIGHT_OUNCE` | The weight is measured in ounces. | -| `IMPERIAL_POUND` | The weight is measured in pounds. | -| `IMPERIAL_STONE` | The weight is measured in stones. | -| `METRIC_MILLIGRAM` | The weight is measured in milligrams. | -| `METRIC_GRAM` | The weight is measured in grams. | -| `METRIC_KILOGRAM` | The weight is measured in kilograms. | - +## Measurement Unit Weight + +Unit of weight used to measure a quantity. + +### Enumeration + +`MeasurementUnitWeight` + +### Fields + +| Name | Description | +| --- | --- | +| `IMPERIAL_WEIGHT_OUNCE` | The weight is measured in ounces. | +| `IMPERIAL_POUND` | The weight is measured in pounds. | +| `IMPERIAL_STONE` | The weight is measured in stones. | +| `METRIC_MILLIGRAM` | The weight is measured in milligrams. | +| `METRIC_GRAM` | The weight is measured in grams. | +| `METRIC_KILOGRAM` | The weight is measured in kilograms. | + diff --git a/doc/models/measurement-unit.md b/doc/models/measurement-unit.md index 0ce2916b..6aec1219 100644 --- a/doc/models/measurement-unit.md +++ b/doc/models/measurement-unit.md @@ -1,37 +1,38 @@ -## Measurement Unit - -Represents a unit of measurement to use with a quantity, such as ounces -or inches. Exactly one of the following fields are required: `custom_unit`, -`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`. - -The `family` field describes the type of measurement. For example, -ounces are in the weight family. - -### Structure - -`MeasurementUnit` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `custom_unit` | [`Measurement Unit Custom Hash`](/doc/models/measurement-unit-custom.md) | Optional | The information needed to define a custom unit, provided by the seller. | -| `area_unit` | [`String (Measurement Unit Area)`](/doc/models/measurement-unit-area.md) | Optional | Unit of area used to measure a quantity. | -| `length_unit` | [`String (Measurement Unit Length)`](/doc/models/measurement-unit-length.md) | Optional | The unit of length used to measure a quantity. | -| `volume_unit` | [`String (Measurement Unit Volume)`](/doc/models/measurement-unit-volume.md) | Optional | The unit of volume used to measure a quantity. | -| `weight_unit` | [`String (Measurement Unit Weight)`](/doc/models/measurement-unit-weight.md) | Optional | Unit of weight used to measure a quantity. | -| `generic_unit` | [`String (Measurement Unit Generic)`](/doc/models/measurement-unit-generic.md) | Optional | A custom unit of measurement defined by the user. | - -### Example (as JSON) - -```json -{ - "custom_unit": null, - "area_unit": null, - "length_unit": null, - "volume_unit": null, - "weight_unit": null, - "generic_unit": null -} -``` - +## Measurement Unit + +Represents a unit of measurement to use with a quantity, such as ounces +or inches. Exactly one of the following fields are required: `custom_unit`, +`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`. + +### Structure + +`MeasurementUnit` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_unit` | [`Measurement Unit Custom Hash`](/doc/models/measurement-unit-custom.md) | Optional | The information needed to define a custom unit, provided by the seller. | +| `area_unit` | [`String (Measurement Unit Area)`](/doc/models/measurement-unit-area.md) | Optional | Unit of area used to measure a quantity. | +| `length_unit` | [`String (Measurement Unit Length)`](/doc/models/measurement-unit-length.md) | Optional | The unit of length used to measure a quantity. | +| `volume_unit` | [`String (Measurement Unit Volume)`](/doc/models/measurement-unit-volume.md) | Optional | The unit of volume used to measure a quantity. | +| `weight_unit` | [`String (Measurement Unit Weight)`](/doc/models/measurement-unit-weight.md) | Optional | Unit of weight used to measure a quantity. | +| `generic_unit` | [`String (Measurement Unit Generic)`](/doc/models/measurement-unit-generic.md) | Optional | A custom unit of measurement defined by the user. | +| `time_unit` | [`String (Measurement Unit Time)`](/doc/models/measurement-unit-time.md) | Optional | Unit of time used to measure a quantity (a duration). | +| `type` | [`String (Measurement Unit Unit Type)`](/doc/models/measurement-unit-unit-type.md) | Optional | Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum. | + +### Example (as JSON) + +```json +{ + "custom_unit": null, + "area_unit": null, + "length_unit": null, + "volume_unit": null, + "weight_unit": null, + "generic_unit": null, + "time_unit": null, + "type": null +} +``` + diff --git a/doc/models/merchant-status.md b/doc/models/merchant-status.md new file mode 100644 index 00000000..e884c3c2 --- /dev/null +++ b/doc/models/merchant-status.md @@ -0,0 +1,13 @@ +## Merchant Status + +### Enumeration + +`MerchantStatus` + +### Fields + +| Name | Description | +| --- | --- | +| `ACTIVE` | A fully operational merchant account. The merchant can interact with Square products and APIs. | +| `INACTIVE` | A functionally limited merchant account. The merchant can only have limited interaction
via Square APIs. The merchant cannot access the seller dashboard. | + diff --git a/doc/models/merchant.md b/doc/models/merchant.md new file mode 100644 index 00000000..a8c57156 --- /dev/null +++ b/doc/models/merchant.md @@ -0,0 +1,32 @@ +## Merchant + +Represents a Square seller. + +### Structure + +`Merchant` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The Square-issued ID of the merchant. | +| `business_name` | `String` | Optional | The business name of the merchant. | +| `country` | [`String (Country)`](/doc/models/country.md) | | Indicates the country associated with another entity, such as a business.
Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). | +| `language_code` | `String` | Optional | The language code associated with the merchant account, in BCP 47 format. | +| `currency` | [`String (Currency)`](/doc/models/currency.md) | Optional | Indicates the associated currency for an amount of money. Values correspond
to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). | +| `status` | [`String (Merchant Status)`](/doc/models/merchant-status.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "id": null, + "business_name": null, + "country": "FO", + "language_code": null, + "currency": null, + "status": null +} +``` + diff --git a/doc/models/money.md b/doc/models/money.md index 54b7a93f..828aa6f0 100644 --- a/doc/models/money.md +++ b/doc/models/money.md @@ -1,29 +1,24 @@ -## Money - -Represents an amount of money. - -__Important:__ Unlike version 1 of the Connect API, __all monetary amounts -returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative -if they represent money being paid _by_ a merchant, instead of money being -paid _to_ a merchant.) - -### Structure - -`Money` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `amount` | `Long` | Optional | The amount of money, in the smallest denomination of the
currency indicated by `currency`. For example, when `currency` is `USD`,
`amount` is in cents. | -| `currency` | [`String (Currency)`](/doc/models/currency.md) | Optional | Indicates the associated currency for an amount of money. Values correspond
to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). | - -### Example (as JSON) - -```json -{ - "amount": null, - "currency": null -} -``` - +## Money + +Represents an amount of money. `Money` fields can be signed or unsigned. + +### Structure + +`Money` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `amount` | `Long` | Optional | The amount of money, in the smallest denomination of the currency
indicated by `currency`. For example, when `currency` is `USD`, `amount` is
in cents. Monetary amounts can be positive or negative. See the specific
API documentation to determine the meaning of the sign in a particular case. | +| `currency` | [`String (Currency)`](/doc/models/currency.md) | Optional | Indicates the associated currency for an amount of money. Values correspond
to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). | + +### Example (as JSON) + +```json +{ + "amount": null, + "currency": null +} +``` + diff --git a/doc/models/obtain-token-request.md b/doc/models/obtain-token-request.md index 0877413b..2f5020ad 100644 --- a/doc/models/obtain-token-request.md +++ b/doc/models/obtain-token-request.md @@ -1,32 +1,32 @@ -## Obtain Token Request - -### Structure - -`ObtainTokenRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `client_id` | `String` | | The Square-issued ID of your application, available from the [application dashboard](https://connect.squareup.com/apps). | -| `client_secret` | `String` | | The Square-issued application secret for your application,
available from the [application dashboard](https://connect.squareup.com/apps). | -| `code` | `String` | Optional | The authorization code to exchange.
This is required if `grant_type` is set to `authorization_code`, to indicate that
the application wants to exchange an authorization code for an OAuth access token. | -| `redirect_uri` | `String` | Optional | The redirect URL assigned in the [application dashboard](https://connect.squareup.com/apps). | -| `grant_type` | `String` | | Specifies the method to request an OAuth access token.
Valid values are: `authorization_code`, `refresh_token`, and `migration_token` | -| `refresh_token` | `String` | Optional | A valid refresh token for generating a new OAuth access token.
A valid refresh token is required if `grant_type` is set to `refresh_token` ,
to indicate the application wants a replacement for an expired OAuth access token. | -| `migration_token` | `String` | Optional | Legacy OAuth access token obtained using a Connect API version prior
to 2019-03-13. This parameter is required if `grant_type` is set to
`migration_token` to indicate that the application wants to get a replacement
OAuth access token. The response also returns a refresh token.
For more information, see [Migrate to Using Refresh Tokens](https://developer.squareup.com/docs/authz/oauth/migration). | - -### Example (as JSON) - -```json -{ - "client_id": "client_id8", - "client_secret": "client_secret8", - "code": null, - "redirect_uri": null, - "grant_type": "grant_type4", - "refresh_token": null, - "migration_token": null -} -``` - +## Obtain Token Request + +### Structure + +`ObtainTokenRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `client_id` | `String` | | The Square-issued ID of your application, available from the [application dashboard](https://connect.squareup.com/apps). | +| `client_secret` | `String` | | The Square-issued application secret for your application,
available from the [application dashboard](https://connect.squareup.com/apps). | +| `code` | `String` | Optional | The authorization code to exchange.
This is required if `grant_type` is set to `authorization_code`, to indicate that
the application wants to exchange an authorization code for an OAuth access token. | +| `redirect_uri` | `String` | Optional | The redirect URL assigned in the [application dashboard](https://connect.squareup.com/apps). | +| `grant_type` | `String` | | Specifies the method to request an OAuth access token.
Valid values are: `authorization_code`, `refresh_token`, and `migration_token` | +| `refresh_token` | `String` | Optional | A valid refresh token for generating a new OAuth access token.
A valid refresh token is required if `grant_type` is set to `refresh_token` ,
to indicate the application wants a replacement for an expired OAuth access token. | +| `migration_token` | `String` | Optional | Legacy OAuth access token obtained using a Connect API version prior
to 2019-03-13. This parameter is required if `grant_type` is set to
`migration_token` to indicate that the application wants to get a replacement
OAuth access token. The response also returns a refresh token.
For more information, see [Migrate to Using Refresh Tokens](https://developer.squareup.com/docs/authz/oauth/migration). | + +### Example (as JSON) + +```json +{ + "client_id": "client_id8", + "client_secret": "client_secret8", + "code": null, + "redirect_uri": null, + "grant_type": "grant_type4", + "refresh_token": null, + "migration_token": null +} +``` + diff --git a/doc/models/obtain-token-response.md b/doc/models/obtain-token-response.md index 1c7fea22..3a5c4e5f 100644 --- a/doc/models/obtain-token-response.md +++ b/doc/models/obtain-token-response.md @@ -1,30 +1,30 @@ -## Obtain Token Response - -### Structure - -`ObtainTokenResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `access_token` | `String` | Optional | A valid OAuth access token. OAuth access tokens are 64 bytes long.
Provide the access token in a header with every request to Connect API
endpoints. See the [Build with OAuth](https://developer.squareup.com/docs/authz/oauth/build-with-the-api) guide
for more information. | -| `token_type` | `String` | Optional | This value is always _bearer_. | -| `expires_at` | `String` | Optional | The date when access_token expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format. | -| `merchant_id` | `String` | Optional | The ID of the authorizing merchant's business. | -| `subscription_id` | `String` | Optional | __LEGACY FIELD__. The ID of a subscription plan the merchant signed up
for. Only present if the merchant signed up for a subscription during authorization. | -| `plan_id` | `String` | Optional | __LEGACY FIELD__. The ID of the subscription plan the merchant signed
up for. Only present if the merchant signed up for a subscription during
authorization. | -| `id_token` | `String` | Optional | Then OpenID token belonging to this this person. Only present if the OPENID scope is included in the authorize request. | -| `refresh_token` | `String` | Optional | A refresh token.
For more information, see [OAuth access token management](https://developer.squareup.com/docs/authz/oauth/how-it-works#oauth-access-token-management). | - -### Example (as JSON) - -```json -{ - "access_token": "ACCESS_TOKEN", - "token_type": "bearer", - "expires_at": "2006-01-02T15:04:05Z", - "merchant_id": "MERCHANT_ID" -} -``` - +## Obtain Token Response + +### Structure + +`ObtainTokenResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `access_token` | `String` | Optional | A valid OAuth access token. OAuth access tokens are 64 bytes long.
Provide the access token in a header with every request to Connect API
endpoints. See the [Build with OAuth](https://developer.squareup.com/docs/authz/oauth/build-with-the-api) guide
for more information. | +| `token_type` | `String` | Optional | This value is always _bearer_. | +| `expires_at` | `String` | Optional | The date when access_token expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format. | +| `merchant_id` | `String` | Optional | The ID of the authorizing merchant's business. | +| `subscription_id` | `String` | Optional | __LEGACY FIELD__. The ID of a subscription plan the merchant signed up
for. Only present if the merchant signed up for a subscription during authorization. | +| `plan_id` | `String` | Optional | __LEGACY FIELD__. The ID of the subscription plan the merchant signed
up for. Only present if the merchant signed up for a subscription during
authorization. | +| `id_token` | `String` | Optional | Then OpenID token belonging to this this person. Only present if the OPENID scope is included in the authorize request. | +| `refresh_token` | `String` | Optional | A refresh token.
For more information, see [OAuth access token management](https://developer.squareup.com/docs/authz/oauth/how-it-works#oauth-access-token-management). | + +### Example (as JSON) + +```json +{ + "access_token": "ACCESS_TOKEN", + "token_type": "bearer", + "expires_at": "2006-01-02T15:04:05Z", + "merchant_id": "MERCHANT_ID" +} +``` + diff --git a/doc/models/order-entry.md b/doc/models/order-entry.md index a75a0cc1..8dd31834 100644 --- a/doc/models/order-entry.md +++ b/doc/models/order-entry.md @@ -1,27 +1,27 @@ -## Order Entry - -A lightweight description of an [Order](./models/order.md) that is returned when `returned_entries` is true on a -[SearchOrderRequest](./models/search-order-request.md) - -### Structure - -`OrderEntry` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order_id` | `String` | Optional | The id of the Order | -| `version` | `Integer` | Optional | The current version of the Order. | -| `location_id` | `String` | Optional | The location id the Order belongs to. | - -### Example (as JSON) - -```json -{ - "order_id": null, - "version": null, - "location_id": null -} -``` - +## Order Entry + +A lightweight description of an [Order](#type-order) that is returned when `returned_entries` is true on a +[SearchOrderRequest](#type-searchorderrequest) + +### Structure + +`OrderEntry` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order_id` | `String` | Optional | The id of the Order | +| `version` | `Integer` | Optional | Version number which is incremented each time an update is committed to the order.
Orders that were not created through the API will not include a version and
thus cannot be updated.

[Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders#update-orders). | +| `location_id` | `String` | Optional | The location id the Order belongs to. | + +### Example (as JSON) + +```json +{ + "order_id": null, + "version": null, + "location_id": null +} +``` + diff --git a/doc/models/order-fulfillment-pickup-details-schedule-type.md b/doc/models/order-fulfillment-pickup-details-schedule-type.md index ef306ee9..aafb586e 100644 --- a/doc/models/order-fulfillment-pickup-details-schedule-type.md +++ b/doc/models/order-fulfillment-pickup-details-schedule-type.md @@ -1,15 +1,15 @@ -## Order Fulfillment Pickup Details Schedule Type - -The schedule type of the pickup fulfillment. - -### Enumeration - -`OrderFulfillmentPickupDetailsScheduleType` - -### Fields - -| Name | Description | -| --- | --- | -| `SCHEDULED` | Indicates the fulfillment will be picked up at a scheduled pickup time. | -| `ASAP` | Indicates the fulfillment should be prepared immediately. | - +## Order Fulfillment Pickup Details Schedule Type + +The schedule type of the pickup fulfillment. + +### Enumeration + +`OrderFulfillmentPickupDetailsScheduleType` + +### Fields + +| Name | Description | +| --- | --- | +| `SCHEDULED` | Indicates the fulfillment will be picked up at a scheduled pickup time. | +| `ASAP` | Indicates the fulfillment will be picked up as soon as possible and
should be prepared immediately. | + diff --git a/doc/models/order-fulfillment-pickup-details.md b/doc/models/order-fulfillment-pickup-details.md index 41c4d4e4..769c0ce6 100644 --- a/doc/models/order-fulfillment-pickup-details.md +++ b/doc/models/order-fulfillment-pickup-details.md @@ -1,52 +1,52 @@ -## Order Fulfillment Pickup Details - -Contains details necessary to fulfill a pickup order. - -### Structure - -`OrderFulfillmentPickupDetails` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `recipient` | [`Order Fulfillment Recipient Hash`](/doc/models/order-fulfillment-recipient.md) | Optional | The recipient of a fulfillment. | -| `expires_at` | `String` | Optional | The expiry [timestamp](#workingwithdates) in RFC 3339 format, e.g.,
"2016-09-04T23:59:33.123Z". This timestamp indicates when the pickup fulfillment will
expire if it is not accepted by the merchant. Expiration time can only be set up to 7 days in
the future. If not set, this pickup fulfillment will be automatically accepted when placed. | -| `auto_complete_duration` | `String` | Optional | The auto completion duration in RFC3339 duration format, e.g., "P1W3D". If set, an open
and accepted pickup fulfillment will automatically move to the `COMPLETED` state after this
period of time. If not set, this pickup fulfillment will remain accepted until it is canceled
or completed. | -| `schedule_type` | [`String (Order Fulfillment Pickup Details Schedule Type)`](/doc/models/order-fulfillment-pickup-details-schedule-type.md) | Optional | The schedule type of the pickup fulfillment. | -| `pickup_at` | `String` | Optional | The pickup [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z".
For fulfillments with the schedule type `ASAP`, this is automatically set to the current time
plus the expected duration to prepare the fulfillment. This represents the start of the
pickup window. | -| `pickup_window_duration` | `String` | Optional | The pickup window duration in RFC3339 duration format, e.g., "P1W3D". This duration
represents the window of time for which the order should be picked up after the `pickup_at`
time. Can be used as an informational guideline for merchants. | -| `prep_time_duration` | `String` | Optional | The preparation time duration in RFC3339 duration format, e.g., "P1W3D". This duration
indicates how long it takes the merchant to prepare this fulfillment. | -| `note` | `String` | Optional | A general note about the pickup fulfillment.

Notes are useful for providing additional instructions and are displayed in Square apps. | -| `placed_at` | `String` | Optional | The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z",
indicating when the fulfillment was placed. | -| `accepted_at` | `String` | Optional | The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z",
indicating when the fulfillment was accepted by the merchant. | -| `rejected_at` | `String` | Optional | The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z",
indicating when the fulfillment was rejected. | -| `ready_at` | `String` | Optional | The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z",
indicating when the merchant set the fulfillment as ready for pickup. | -| `expired_at` | `String` | Optional | The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z",
indicating when the fulfillment expired. | -| `picked_up_at` | `String` | Optional | The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z",
indicating when the fulfillment was picked up by the recipient. | -| `canceled_at` | `String` | Optional | The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z",
indicating when the fulfillment was canceled by the merchant or buyer. | -| `cancel_reason` | `String` | Optional | A description of why the pickup was canceled. Max length is 100 characters. | - -### Example (as JSON) - -```json -{ - "recipient": null, - "expires_at": null, - "auto_complete_duration": null, - "schedule_type": null, - "pickup_at": null, - "pickup_window_duration": null, - "prep_time_duration": null, - "note": null, - "placed_at": null, - "accepted_at": null, - "rejected_at": null, - "ready_at": null, - "expired_at": null, - "picked_up_at": null, - "canceled_at": null, - "cancel_reason": null -} -``` - +## Order Fulfillment Pickup Details + +Contains details necessary to fulfill a pickup order. + +### Structure + +`OrderFulfillmentPickupDetails` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `recipient` | [`Order Fulfillment Recipient Hash`](/doc/models/order-fulfillment-recipient.md) | Optional | Contains information on the recipient of a fulfillment. | +| `expires_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when this fulfillment
will expire if it is not accepted. Must be in RFC 3339 format
e.g., "2016-09-04T23:59:33.123Z". Expiration time can only be set up to 7
days in the future. If `expires_at` is not set, this pickup fulfillment
will be automatically accepted when placed. | +| `auto_complete_duration` | `String` | Optional | The duration of time after which an open and accepted pickup fulfillment
will automatically move to the `COMPLETED` state. Must be in RFC3339
duration format e.g., "P1W3D".

If not set, this pickup fulfillment will remain accepted until it is canceled or completed. | +| `schedule_type` | [`String (Order Fulfillment Pickup Details Schedule Type)`](/doc/models/order-fulfillment-pickup-details-schedule-type.md) | Optional | The schedule type of the pickup fulfillment. | +| `pickup_at` | `String` | Optional | The [timestamp](#workingwithdates) that represents the start of the pickup window.
Must be in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z".
For fulfillments with the schedule type `ASAP`, this is automatically set
to the current time plus the expected duration to prepare the fulfillment. | +| `pickup_window_duration` | `String` | Optional | The window of time in which the order should be picked up after the `pickup_at` timestamp.
Must be in RFC3339 duration format, e.g., "P1W3D". Can be used as an
informational guideline for merchants. | +| `prep_time_duration` | `String` | Optional | The duration of time it takes to prepare this fulfillment.
Must be in RFC3339 duration format, e.g., "P1W3D". | +| `note` | `String` | Optional | A note meant to provide additional instructions about the pickup
fulfillment displayed in the Square Point of Sale and set by the API. | +| `placed_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when the fulfillment
was placed. Must be in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". | +| `accepted_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when the fulfillment
was accepted. In RFC3339 timestamp format,
e.g., "2016-09-04T23:59:33.123Z". | +| `rejected_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when the fulfillment
was rejected. In RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". | +| `ready_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when the fulfillment is
marked as ready for pickup. In RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". | +| `expired_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when the fulfillment expired.
In RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". | +| `picked_up_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when the fulfillment
was picked up by the recipient. In RFC3339 timestamp format,
e.g., "2016-09-04T23:59:33.123Z". | +| `canceled_at` | `String` | Optional | The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z",
indicating when the fulfillment was canceled. | +| `cancel_reason` | `String` | Optional | A description of why the pickup was canceled. Max length: 100 characters. | + +### Example (as JSON) + +```json +{ + "recipient": null, + "expires_at": null, + "auto_complete_duration": null, + "schedule_type": null, + "pickup_at": null, + "pickup_window_duration": null, + "prep_time_duration": null, + "note": null, + "placed_at": null, + "accepted_at": null, + "rejected_at": null, + "ready_at": null, + "expired_at": null, + "picked_up_at": null, + "canceled_at": null, + "cancel_reason": null +} +``` + diff --git a/doc/models/order-fulfillment-recipient.md b/doc/models/order-fulfillment-recipient.md index c3a4593d..9065786b 100644 --- a/doc/models/order-fulfillment-recipient.md +++ b/doc/models/order-fulfillment-recipient.md @@ -1,30 +1,30 @@ -## Order Fulfillment Recipient - -The recipient of a fulfillment. - -### Structure - -`OrderFulfillmentRecipient` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `customer_id` | `String` | Optional | The Customer ID of the customer associated with the fulfillment.

If customer_id is provided, the corresponding recipient information fields
(`display_name`, `email_address`, and `phone_number`) are automatically populated from the relevant
customer profile. If the targeted profile information does not contain the necessary required
information, the request will result in an error. | -| `display_name` | `String` | Optional | The display name of the fulfillment recipient.

If provided, overrides the value from customer profile indicated by customer_id. | -| `email_address` | `String` | Optional | The email address of the fulfillment recipient.

If provided, overrides the value from customer profile indicated by customer_id. | -| `phone_number` | `String` | Optional | The phone number of the fulfillment recipient.

If provided, overrides the value from customer profile indicated by customer_id. | -| `address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | - -### Example (as JSON) - -```json -{ - "customer_id": null, - "display_name": null, - "email_address": null, - "phone_number": null, - "address": null -} -``` - +## Order Fulfillment Recipient + +Contains information on the recipient of a fulfillment. + +### Structure + +`OrderFulfillmentRecipient` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `customer_id` | `String` | Optional | The Customer ID of the customer associated with the fulfillment.

If `customer_id` is provided, the fulfillment recipient's `display_name`,
`email_address`, and `phone_number` are automatically populated from the
targeted customer profile. If these fields are set in the request, the request
values will override the information from the customer profile. If the
targeted customer profile does not contain the necessary information and
these fields are left unset, the request will result in an error. | +| `display_name` | `String` | Optional | The display name of the fulfillment recipient.

If provided, overrides the value pulled from the customer profile indicated by `customer_id`. | +| `email_address` | `String` | Optional | The email address of the fulfillment recipient.

If provided, overrides the value pulled from the customer profile indicated by `customer_id`. | +| `phone_number` | `String` | Optional | The phone number of the fulfillment recipient.

If provided, overrides the value pulled from the customer profile indicated by `customer_id`. | +| `address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | + +### Example (as JSON) + +```json +{ + "customer_id": null, + "display_name": null, + "email_address": null, + "phone_number": null, + "address": null +} +``` + diff --git a/doc/models/order-fulfillment-shipment-details.md b/doc/models/order-fulfillment-shipment-details.md index cf2b9d1d..7c43b184 100644 --- a/doc/models/order-fulfillment-shipment-details.md +++ b/doc/models/order-fulfillment-shipment-details.md @@ -1,48 +1,50 @@ -## Order Fulfillment Shipment Details - -### Structure - -`OrderFulfillmentShipmentDetails` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `recipient` | [`Order Fulfillment Recipient Hash`](/doc/models/order-fulfillment-recipient.md) | Optional | The recipient of a fulfillment. | -| `carrier` | `String` | Optional | The shipping carrier.
e.g. UPS, FedEx, USPS, etc. | -| `shipping_note` | `String` | Optional | A note from the merchant or the buyer with additional information for the carrier. | -| `shipping_type` | `String` | Optional | A description of the class or type of shipping product purchased from the carrier.
e.g. Regular, Express | -| `tracking_number` | `String` | Optional | The reference number for the shipment provided by the carrier. | -| `tracking_url` | `String` | Optional | A link to the tracking webpage on the carrier's website. | -| `placed_at` | `String` | Optional | The date the shipment was requested. | -| `in_progress_at` | `String` | Optional | The date the shipment started being prepared. | -| `packaged_at` | `String` | Optional | The date the shipment was packaged. | -| `expected_shipped_at` | `String` | Optional | The expected shipment date. | -| `shipped_at` | `String` | Optional | The date the shipment was given to the carrier. | -| `canceled_at` | `String` | Optional | The date the shipment was canceled by either the merchant or the buyer. | -| `cancel_reason` | `String` | Optional | A description of why the shipment was canceled. | -| `failed_at` | `String` | Optional | The date the shipment failed to be completed. | -| `failure_reason` | `String` | Optional | A description of why the shipment failed to be completed. | - -### Example (as JSON) - -```json -{ - "recipient": null, - "carrier": null, - "shipping_note": null, - "shipping_type": null, - "tracking_number": null, - "tracking_url": null, - "placed_at": null, - "in_progress_at": null, - "packaged_at": null, - "expected_shipped_at": null, - "shipped_at": null, - "canceled_at": null, - "cancel_reason": null, - "failed_at": null, - "failure_reason": null -} -``` - +## Order Fulfillment Shipment Details + +Contains details necessary to fulfill a shipment order. + +### Structure + +`OrderFulfillmentShipmentDetails` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `recipient` | [`Order Fulfillment Recipient Hash`](/doc/models/order-fulfillment-recipient.md) | Optional | Contains information on the recipient of a fulfillment. | +| `carrier` | `String` | Optional | The shipping carrier being used to ship this fulfillment
e.g. UPS, FedEx, USPS, etc. | +| `shipping_note` | `String` | Optional | A note with additional information for the shipping carrier. | +| `shipping_type` | `String` | Optional | A description of the type of shipping product purchased from the carrier.
e.g. First Class, Priority, Express | +| `tracking_number` | `String` | Optional | The reference number provided by the carrier to track the shipment's progress. | +| `tracking_url` | `String` | Optional | A link to the tracking webpage on the carrier's website. | +| `placed_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when the shipment was
requested. Must be in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". | +| `in_progress_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when this fulfillment was
moved to the `RESERVED` state. Indicates that preparation of this shipment has begun.
Must be in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". | +| `packaged_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when this fulfillment
was moved to the `PREPARED` state. Indicates that the fulfillment is packaged.
Must be in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". | +| `expected_shipped_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when the shipment is
expected to be delivered to the shipping carrier. Must be in RFC3339 timestamp
format, e.g., "2016-09-04T23:59:33.123Z". | +| `shipped_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when this fulfillment
was moved to the `COMPLETED`state. Indicates that the fulfillment has been given
to the shipping carrier. Must be in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". | +| `canceled_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating the shipment was canceled.
Must be in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". | +| `cancel_reason` | `String` | Optional | A description of why the shipment was canceled. | +| `failed_at` | `String` | Optional | The [timestamp](#workingwithdates) indicating when the shipment
failed to be completed. Must be in RFC3339 timestamp format, e.g.,
"2016-09-04T23:59:33.123Z". | +| `failure_reason` | `String` | Optional | A description of why the shipment failed to be completed. | + +### Example (as JSON) + +```json +{ + "recipient": null, + "carrier": null, + "shipping_note": null, + "shipping_type": null, + "tracking_number": null, + "tracking_url": null, + "placed_at": null, + "in_progress_at": null, + "packaged_at": null, + "expected_shipped_at": null, + "shipped_at": null, + "canceled_at": null, + "cancel_reason": null, + "failed_at": null, + "failure_reason": null +} +``` + diff --git a/doc/models/order-fulfillment-state.md b/doc/models/order-fulfillment-state.md index 81b3e724..57c4dd57 100644 --- a/doc/models/order-fulfillment-state.md +++ b/doc/models/order-fulfillment-state.md @@ -1,19 +1,19 @@ -## Order Fulfillment State - -The state of the fulfillment. - -### Enumeration - -`OrderFulfillmentState` - -### Fields - -| Name | Description | -| --- | --- | -| `PROPOSED` | Indicates the fulfillment has been proposed. | -| `RESERVED` | Indicates the fulfillment has been reserved. | -| `PREPARED` | Indicates the fulfillment has been prepared. | -| `COMPLETED` | Indicates the fulfillment was successfully completed. | -| `CANCELED` | Indicates the fulfillment was canceled by either the merchant or buyer. | -| `FAILED` | Indicates the fulfillment failed to be completed but was not explicitly canceled. | - +## Order Fulfillment State + +The current state of this fulfillment. + +### Enumeration + +`OrderFulfillmentState` + +### Fields + +| Name | Description | +| --- | --- | +| `PROPOSED` | Indicates the fulfillment has been proposed. | +| `RESERVED` | Indicates the fulfillment has been reserved. | +| `PREPARED` | Indicates the fulfillment has been prepared. | +| `COMPLETED` | Indicates the fulfillment was successfully completed. | +| `CANCELED` | Indicates the fulfillment was canceled. | +| `FAILED` | Indicates the fulfillment failed to be completed but was not explicitly
canceled. | + diff --git a/doc/models/order-fulfillment-type.md b/doc/models/order-fulfillment-type.md index c0accc5f..ade0584c 100644 --- a/doc/models/order-fulfillment-type.md +++ b/doc/models/order-fulfillment-type.md @@ -1,15 +1,15 @@ -## Order Fulfillment Type - -The type of fulfillment. - -### Enumeration - -`OrderFulfillmentType` - -### Fields - -| Name | Description | -| --- | --- | -| `PICKUP` | A fulfillment to be picked up by a recipient. | -| `SHIPMENT` | A fulfillment to be shipped by a carrier. | - +## Order Fulfillment Type + +The type of fulfillment. + +### Enumeration + +`OrderFulfillmentType` + +### Fields + +| Name | Description | +| --- | --- | +| `PICKUP` | A fulfillment to be picked up from a physical [location](#type-location)
by a recipient. | +| `SHIPMENT` | A fulfillment to be shipped by a shipping carrier. | + diff --git a/doc/models/order-fulfillment.md b/doc/models/order-fulfillment.md index 8d3bcb47..4f222d60 100644 --- a/doc/models/order-fulfillment.md +++ b/doc/models/order-fulfillment.md @@ -1,30 +1,32 @@ -## Order Fulfillment - -Contains details on how to fulfill this order. - -### Structure - -`OrderFulfillment` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the fulfillment only within this order. | -| `type` | [`String (Order Fulfillment Type)`](/doc/models/order-fulfillment-type.md) | Optional | The type of fulfillment. | -| `state` | [`String (Order Fulfillment State)`](/doc/models/order-fulfillment-state.md) | Optional | The state of the fulfillment. | -| `pickup_details` | [`Order Fulfillment Pickup Details Hash`](/doc/models/order-fulfillment-pickup-details.md) | Optional | Contains details necessary to fulfill a pickup order. | -| `shipment_details` | [`Order Fulfillment Shipment Details Hash`](/doc/models/order-fulfillment-shipment-details.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "uid": null, - "type": null, - "state": null, - "pickup_details": null, - "shipment_details": null -} -``` - +## Order Fulfillment + +Contains details on how to fulfill this order. + +### Structure + +`OrderFulfillment` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the fulfillment only within this order. | +| `type` | [`String (Order Fulfillment Type)`](/doc/models/order-fulfillment-type.md) | Optional | The type of fulfillment. | +| `state` | [`String (Order Fulfillment State)`](/doc/models/order-fulfillment-state.md) | Optional | The current state of this fulfillment. | +| `metadata` | `Hash` | Optional | Application-defined data attached to this fulfillment. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (personally
identifiable information, card details, etc.).

Keys written by applications must be 60 characters or less and must be in the character set
`[a-zA-Z0-9_-]`. Entries may also include metadata generated by Square. These keys are prefixed
with a namespace, separated from the key with a ':' character.

Values have a max length of 255 characters.

An application may have up to 10 entries per metadata field.

Entries written by applications are private and can only be read or modified by the same
application.

See [Metadata](https://developer.squareup.com/docs/build-basics/metadata) for more information. | +| `pickup_details` | [`Order Fulfillment Pickup Details Hash`](/doc/models/order-fulfillment-pickup-details.md) | Optional | Contains details necessary to fulfill a pickup order. | +| `shipment_details` | [`Order Fulfillment Shipment Details Hash`](/doc/models/order-fulfillment-shipment-details.md) | Optional | Contains details necessary to fulfill a shipment order. | + +### Example (as JSON) + +```json +{ + "uid": null, + "type": null, + "state": null, + "metadata": null, + "pickup_details": null, + "shipment_details": null +} +``` + diff --git a/doc/models/order-line-item-applied-discount.md b/doc/models/order-line-item-applied-discount.md index 520d1415..683e69c2 100644 --- a/doc/models/order-line-item-applied-discount.md +++ b/doc/models/order-line-item-applied-discount.md @@ -1,31 +1,31 @@ -## Order Line Item Applied Discount - -Represents an applied portion of a discount to a line item in an order. - -Order scoped discounts will automatically have applied discounts present for each line item. -Line item scoped discounts must have applied discounts added manually for any applicable line -items. The corresponding applied money will automatically be computed based on participating -line items. - -### Structure - -`OrderLineItemAppliedDiscount` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the applied discount only within this order. | -| `discount_uid` | `String` | | The `uid` of the discount for which this applied discount represents. Must reference
a discount present in the `order.discounts` field.

This field is immutable. To change which discounts apply to a line item, delete and add new
`OrderLineItemAppliedDiscount`s. | -| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "uid": null, - "discount_uid": "discount_uid4", - "applied_money": null -} -``` - +## Order Line Item Applied Discount + +Represents an applied portion of a discount to a line item in an order. + +Order scoped discounts will automatically have applied discounts present for each line item. +Line item scoped discounts must have applied discounts added manually for any applicable line +items. The corresponding applied money will automatically be computed based on participating +line items. + +### Structure + +`OrderLineItemAppliedDiscount` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the applied discount only within this order. | +| `discount_uid` | `String` | | The `uid` of the discount the applied discount represents. Must
reference a discount present in the `order.discounts` field.

This field is immutable. To change which discounts apply to a line item,
you must delete the discount and re-add it as a new `OrderLineItemAppliedDiscount`. | +| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "uid": null, + "discount_uid": "discount_uid4", + "applied_money": null +} +``` + diff --git a/doc/models/order-line-item-applied-tax.md b/doc/models/order-line-item-applied-tax.md index d065da6d..182353c0 100644 --- a/doc/models/order-line-item-applied-tax.md +++ b/doc/models/order-line-item-applied-tax.md @@ -1,31 +1,31 @@ -## Order Line Item Applied Tax - -Represents an applied portion of a tax to a line item in an order. - -Order scoped taxes will automatically have applied taxes present for each line item. -Line item scoped taxes must have applied taxes added manually for any applicable line items. -The corresponding applied money will automatically be computed based on participating line -items. - -### Structure - -`OrderLineItemAppliedTax` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the applied tax only within this order. | -| `tax_uid` | `String` | | The `uid` of the tax for which this applied tax represents. Must reference
a tax present in the `order.taxes` field.

This field is immutable. To change which taxes apply to a line item, delete and add new
`OrderLineItemAppliedTax`s. | -| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "uid": null, - "tax_uid": "tax_uid4", - "applied_money": null -} -``` - +## Order Line Item Applied Tax + +Represents an applied portion of a tax to a line item in an order. + +Order-scoped taxes automatically include the applied taxes in each line item. +Line item taxes must be referenced from any applicable line items. +The corresponding applied money is automatically computed, based on the +set of participating line items. + +### Structure + +`OrderLineItemAppliedTax` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the applied tax only within this order. | +| `tax_uid` | `String` | | The `uid` of the tax for which this applied tax represents. Must reference
a tax present in the `order.taxes` field.

This field is immutable. To change which taxes apply to a line item, delete and add new
`OrderLineItemAppliedTax`s. | +| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "uid": null, + "tax_uid": "tax_uid4", + "applied_money": null +} +``` + diff --git a/doc/models/order-line-item-discount-scope.md b/doc/models/order-line-item-discount-scope.md index 5739c0d6..05a4e3ea 100644 --- a/doc/models/order-line-item-discount-scope.md +++ b/doc/models/order-line-item-discount-scope.md @@ -1,16 +1,16 @@ -## Order Line Item Discount Scope - -Indicates whether this is a line item or order level discount. - -### Enumeration - -`OrderLineItemDiscountScope` - -### Fields - -| Name | Description | -| --- | --- | -| `OTHER_DISCOUNT_SCOPE` | Used for reporting only.
The original transaction discount scope is currently not supported by the API. | -| `LINE_ITEM` | The discount should be applied to only line items specified by
`OrderLineItemAppliedDiscount` reference records. | -| `ORDER` | The discount should be applied to the entire order. | - +## Order Line Item Discount Scope + +Indicates whether this is a line item or order level discount. + +### Enumeration + +`OrderLineItemDiscountScope` + +### Fields + +| Name | Description | +| --- | --- | +| `OTHER_DISCOUNT_SCOPE` | Used for reporting only.
The original transaction discount scope is currently not supported by the API. | +| `LINE_ITEM` | The discount should be applied to only line items specified by
`OrderLineItemAppliedDiscount` reference records. | +| `ORDER` | The discount should be applied to the entire order. | + diff --git a/doc/models/order-line-item-discount-type.md b/doc/models/order-line-item-discount-type.md index a0ab5966..32266b8d 100644 --- a/doc/models/order-line-item-discount-type.md +++ b/doc/models/order-line-item-discount-type.md @@ -1,18 +1,18 @@ -## Order Line Item Discount Type - -Indicates how the discount is applied to the associated line item or order. - -### Enumeration - -`OrderLineItemDiscountType` - -### Fields - -| Name | Description | -| --- | --- | -| `UNKNOWN_DISCOUNT` | Used for reporting only.
The original transaction discount type is currently not supported by the API. | -| `FIXED_PERCENTAGE` | Apply the discount as a fixed percentage (e.g., 5%) off the item price. | -| `FIXED_AMOUNT` | Apply the discount as a fixed monetary value (e.g., $1.00) off the item price. | -| `VARIABLE_PERCENTAGE` | Apply the discount as a variable percentage off the item price.

The variable percentage is defined in Register POS apps. Specific value is assigned at the time of the purchase. | -| `VARIABLE_AMOUNT` | Apply the discount as a variable amount off the item price.

The variable amount is defined in Square POS app. Specific value is assigned at the time of the purchase. | - +## Order Line Item Discount Type + +Indicates how the discount is applied to the associated line item or order. + +### Enumeration + +`OrderLineItemDiscountType` + +### Fields + +| Name | Description | +| --- | --- | +| `UNKNOWN_DISCOUNT` | Used for reporting only.
The original transaction discount type is currently not supported by the API. | +| `FIXED_PERCENTAGE` | Apply the discount as a fixed percentage (e.g., 5%) off the item price. | +| `FIXED_AMOUNT` | Apply the discount as a fixed monetary value (e.g., $1.00) off the item price. | +| `VARIABLE_PERCENTAGE` | Apply the discount as a variable percentage based on the item
price.

The specific discount percentage of a `VARIABLE_PERCENTAGE` discount
is assigned at the time of the purchase. | +| `VARIABLE_AMOUNT` | Apply the discount as a variable amount based on the item price.

The specific discount amount of a `VARIABLE_AMOUNT` discount
is assigned at the time of the purchase. | + diff --git a/doc/models/order-line-item-discount.md b/doc/models/order-line-item-discount.md index 5f25f6f8..d8d1215f 100644 --- a/doc/models/order-line-item-discount.md +++ b/doc/models/order-line-item-discount.md @@ -1,40 +1,43 @@ -## Order Line Item Discount - -Represents a discount that applies to one or more line items in an -order. - -Fixed-amount, order-scoped discounts are distributed across all non-zero line item totals. -The amount distributed to each line item is relative to that item’s contribution to the order subtotal. - -### Structure - -`OrderLineItemDiscount` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the discount only within this order. | -| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogDiscount](./models/catalog-discount.md). | -| `name` | `String` | Optional | The discount's name. | -| `type` | [`String (Order Line Item Discount Type)`](/doc/models/order-line-item-discount-type.md) | Optional | Indicates how the discount is applied to the associated line item or order. | -| `percentage` | `String` | Optional | The percentage of the discount, as a string representation of a decimal number.
A value of `7.25` corresponds to a percentage of 7.25%.

The percentage won't be set for an amount-based discount. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `scope` | [`String (Order Line Item Discount Scope)`](/doc/models/order-line-item-discount-scope.md) | Optional | Indicates whether this is a line item or order level discount. | - -### Example (as JSON) - -```json -{ - "uid": null, - "catalog_object_id": null, - "name": null, - "type": null, - "percentage": null, - "amount_money": null, - "applied_money": null, - "scope": null -} -``` - +## Order Line Item Discount + +Represents a discount that applies to one or more line items in an +order. + +Fixed-amount, order-scoped discounts are distributed across all non-zero line item totals. +The amount distributed to each line item is relative to the +amount contributed by the item to the order subtotal. + +### Structure + +`OrderLineItemDiscount` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the discount only within this order. | +| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogDiscount](#type-catalogdiscount). | +| `name` | `String` | Optional | The discount's name. | +| `type` | [`String (Order Line Item Discount Type)`](/doc/models/order-line-item-discount-type.md) | Optional | Indicates how the discount is applied to the associated line item or order. | +| `percentage` | `String` | Optional | The percentage of the discount, as a string representation of a decimal number.
A value of `7.25` corresponds to a percentage of 7.25%.

`percentage` is not set for amount-based discounts. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `metadata` | `Hash` | Optional | Application-defined data attached to this discount. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (personally
identifiable information, card details, etc.).

Keys written by applications must be 60 characters or less and must be in the character set
`[a-zA-Z0-9_-]`. Entries may also include metadata generated by Square. These keys are prefixed
with a namespace, separated from the key with a ':' character.

Values have a max length of 255 characters.

An application may have up to 10 entries per metadata field.

Entries written by applications are private and can only be read or modified by the same
application.

See [Metadata](https://developer.squareup.com/docs/build-basics/metadata) for more information. | +| `scope` | [`String (Order Line Item Discount Scope)`](/doc/models/order-line-item-discount-scope.md) | Optional | Indicates whether this is a line item or order level discount. | + +### Example (as JSON) + +```json +{ + "uid": null, + "catalog_object_id": null, + "name": null, + "type": null, + "percentage": null, + "amount_money": null, + "applied_money": null, + "metadata": null, + "scope": null +} +``` + diff --git a/doc/models/order-line-item-modifier.md b/doc/models/order-line-item-modifier.md index a0a171ee..bf994b1a 100644 --- a/doc/models/order-line-item-modifier.md +++ b/doc/models/order-line-item-modifier.md @@ -1,30 +1,30 @@ -## Order Line Item Modifier - -A [CatalogModifier](./models/catalog-modifier.md). - -### Structure - -`OrderLineItemModifier` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the modifier only within this order. | -| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogModifier](./models/catalog-modifier.md). | -| `name` | `String` | Optional | The name of the item modifier. | -| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "uid": null, - "catalog_object_id": null, - "name": null, - "base_price_money": null, - "total_price_money": null -} -``` - +## Order Line Item Modifier + +A [CatalogModifier](#type-catalogmodifier). + +### Structure + +`OrderLineItemModifier` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the modifier only within this order. | +| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogModifier](#type-catalogmodifier). | +| `name` | `String` | Optional | The name of the item modifier. | +| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "uid": null, + "catalog_object_id": null, + "name": null, + "base_price_money": null, + "total_price_money": null +} +``` + diff --git a/doc/models/order-line-item-tax-scope.md b/doc/models/order-line-item-tax-scope.md index 7862187e..cc063911 100644 --- a/doc/models/order-line-item-tax-scope.md +++ b/doc/models/order-line-item-tax-scope.md @@ -1,16 +1,16 @@ -## Order Line Item Tax Scope - -Indicates whether this is a line item or order level tax. - -### Enumeration - -`OrderLineItemTaxScope` - -### Fields - -| Name | Description | -| --- | --- | -| `OTHER_TAX_SCOPE` | Used for reporting only.
The original transaction tax scope is currently not supported by the API. | -| `LINE_ITEM` | The tax should be applied to only line items specified by `OrderLineItemAppliedTax`
reference records. | -| `ORDER` | The tax should be applied to the entire order. | - +## Order Line Item Tax Scope + +Indicates whether this is a line item or order level tax. + +### Enumeration + +`OrderLineItemTaxScope` + +### Fields + +| Name | Description | +| --- | --- | +| `OTHER_TAX_SCOPE` | Used for reporting only.
The original transaction tax scope is currently not supported by the API. | +| `LINE_ITEM` | The tax should be applied only to line items specified by
the `OrderLineItemAppliedTax` reference records. | +| `ORDER` | The tax should be applied to the entire order. | + diff --git a/doc/models/order-line-item-tax-type.md b/doc/models/order-line-item-tax-type.md index ad415839..38f6000a 100644 --- a/doc/models/order-line-item-tax-type.md +++ b/doc/models/order-line-item-tax-type.md @@ -1,16 +1,16 @@ -## Order Line Item Tax Type - -Indicates how the tax is applied to the associated line item or order. - -### Enumeration - -`OrderLineItemTaxType` - -### Fields - -| Name | Description | -| --- | --- | -| `UNKNOWN_TAX` | Used for reporting only.
The original transaction tax type is currently not supported by the API. | -| `ADDITIVE` | The tax is an additive tax. The tax amount is added on top of the price.
For example, a $1.00 item with a 10% additive tax would have a total cost to the buyer of $1.10. | -| `INCLUSIVE` | The tax is an inclusive tax. Inclusive taxes are already included in the line item price or order total.
For example, a $1.00 item with a 10% inclusive tax would have a pre-tax cost of $0.91 (91 cents)
and a $0.09 (9 cents) tax for a total cost of $1 to the buyer. | - +## Order Line Item Tax Type + +Indicates how the tax is applied to the associated line item or order. + +### Enumeration + +`OrderLineItemTaxType` + +### Fields + +| Name | Description | +| --- | --- | +| `UNKNOWN_TAX` | Used for reporting only.
The original transaction tax type is currently not supported by the API. | +| `ADDITIVE` | The tax is an additive tax. The tax amount is added on top of the price.
For example, an item with a cost of 1.00 USD and a 10% additive tax would have a total
cost to the buyer of 1.10 USD. | +| `INCLUSIVE` | The tax is an inclusive tax. Inclusive taxes are already included
in the line item price or order total. For example, an item with cost
1.00 USD with a 10% inclusive tax would have a pre-tax cost of 0.91 USD
(91 cents) and a 0.09 (9 cents) tax for a total cost of 1.00 USD to
the buyer. | + diff --git a/doc/models/order-line-item-tax.md b/doc/models/order-line-item-tax.md index d854de64..b8da467b 100644 --- a/doc/models/order-line-item-tax.md +++ b/doc/models/order-line-item-tax.md @@ -1,38 +1,40 @@ -## Order Line Item Tax - -Represents a tax that applies to one or more line items in an order. - -Fixed-amount, order-scoped taxes are distributed across all non-zero line item totals. -The amount distributed to each line item is relative to that item’s contribution to the -order subtotal. - -### Structure - -`OrderLineItemTax` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the tax only within this order. | -| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogTax](./models/catalog-tax.md). | -| `name` | `String` | Optional | The tax's name. | -| `type` | [`String (Order Line Item Tax Type)`](/doc/models/order-line-item-tax-type.md) | Optional | Indicates how the tax is applied to the associated line item or order. | -| `percentage` | `String` | Optional | The percentage of the tax, as a string representation of a decimal number.

A value of `7.25` corresponds to a percentage of 7.25%. | -| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `scope` | [`String (Order Line Item Tax Scope)`](/doc/models/order-line-item-tax-scope.md) | Optional | Indicates whether this is a line item or order level tax. | - -### Example (as JSON) - -```json -{ - "uid": null, - "catalog_object_id": null, - "name": null, - "type": null, - "percentage": null, - "applied_money": null, - "scope": null -} -``` - +## Order Line Item Tax + +Represents a tax that applies to one or more line item in the order. + +Fixed-amount, order-scoped taxes are distributed across all non-zero line item totals. +The amount distributed to each line item is relative to the amount the item +contributes to the order subtotal. + +### Structure + +`OrderLineItemTax` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the tax only within this order. | +| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogTax](#type-catalogtax). | +| `name` | `String` | Optional | The tax's name. | +| `type` | [`String (Order Line Item Tax Type)`](/doc/models/order-line-item-tax-type.md) | Optional | Indicates how the tax is applied to the associated line item or order. | +| `percentage` | `String` | Optional | The percentage of the tax, as a string representation of a decimal
number. For example, a value of `"7.25"` corresponds to a percentage of
7.25%. | +| `metadata` | `Hash` | Optional | Application-defined data attached to this tax. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (personally
identifiable information, card details, etc.).

Keys written by applications must be 60 characters or less and must be in the character set
`[a-zA-Z0-9_-]`. Entries may also include metadata generated by Square. These keys are prefixed
with a namespace, separated from the key with a ':' character.

Values have a max length of 255 characters.

An application may have up to 10 entries per metadata field.

Entries written by applications are private and can only be read or modified by the same
application.

See [Metadata](https://developer.squareup.com/docs/build-basics/metadata) for more information. | +| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `scope` | [`String (Order Line Item Tax Scope)`](/doc/models/order-line-item-tax-scope.md) | Optional | Indicates whether this is a line item or order level tax. | + +### Example (as JSON) + +```json +{ + "uid": null, + "catalog_object_id": null, + "name": null, + "type": null, + "percentage": null, + "metadata": null, + "applied_money": null, + "scope": null +} +``` + diff --git a/doc/models/order-line-item.md b/doc/models/order-line-item.md index 12c2fce9..e8b6a6b0 100644 --- a/doc/models/order-line-item.md +++ b/doc/models/order-line-item.md @@ -1,57 +1,59 @@ -## Order Line Item - -Represents a line item in an order. Each line item describes a different -product to purchase, with its own quantity and price details. - -### Structure - -`OrderLineItem` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the line item only within this order. | -| `name` | `String` | Optional | The name of the line item. | -| `quantity` | `String` | | The quantity purchased, formatted as a decimal number.
For example: `"3"`.

Line items with a `quantity_unit` can have non-integer quantities.
For example: `"1.70000"`. | -| `quantity_unit` | [`Order Quantity Unit Hash`](/doc/models/order-quantity-unit.md) | Optional | Contains the measurement unit for a quantity and a precision which
specifies the number of digits after the decimal point for decimal quantities. | -| `note` | `String` | Optional | The note of the line item. | -| `catalog_object_id` | `String` | Optional | The [CatalogItemVariation](./models/catalog-item-variation.md) id applied to this line item. | -| `variation_name` | `String` | Optional | The name of the variation applied to this line item. | -| `modifiers` | [`Array`](/doc/models/order-line-item-modifier.md) | Optional | The [CatalogModifier](./models/catalog-modifier.md)s applied to this line item. | -| `taxes` | [`Array`](/doc/models/order-line-item-tax.md) | Optional | A list of taxes applied to this line item. On read or retrieve, this list includes both
item-level taxes and any order-level taxes apportioned to this item. When creating an Order,
set your item-level taxes in this list.

This field has been deprecated in favour of `applied_taxes`. Usage of both this field and
`applied_taxes` when creating an order will result in an error. Usage of this field when
sending requests to the UpdateOrder endpoint will result in an error. | -| `discounts` | [`Array`](/doc/models/order-line-item-discount.md) | Optional | A list of discounts applied to this line item. On read or retrieve, this list includes
both item-level discounts and any order-level discounts apportioned to this item. When
creating an Order, set your item-level discounts in this list.

This field has been deprecated in favour of `applied_discounts`. Usage of both this field and
`applied_discounts` when creating an order will result in an error. Usage of this field when
sending requests to the UpdateOrder endpoint will result in an error. | -| `applied_taxes` | [`Array`](/doc/models/order-line-item-applied-tax.md) | Optional | The list of references to taxes applied to this line item. Each `OrderLineItemAppliedTax`
has a `tax_uid` that references the `uid` of a top-level `OrderLineItemTax` that is being
applied to this line item. On reads, the amount applied is populated.

An `OrderLineItemAppliedTax` will be automatically created on every line item for all `ORDER`
scoped taxes that are added to the order. `OrderLineItemAppliedTax` records for `LINE_ITEM`
scoped taxes must be added in requests for the tax to apply to any line items.

To change the amount of a tax, modify the referenced top-level tax. | -| `applied_discounts` | [`Array`](/doc/models/order-line-item-applied-discount.md) | Optional | The list of references to discounts applied to this line item. Each
`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level
`OrderLineItemDiscounts` that is being applied to this line item. On reads, the amount
applied is populated.

An `OrderLineItemAppliedDiscount` will be automatically created on every line item for all
`ORDER` scoped discounts that are added to the order. `OrderLineItemAppliedDiscount` records
for `LINE_ITEM` scoped discounts must be added in requests for the discount to apply to any
line items.

To change the amount of a discount, modify the referenced top-level discount. | -| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `variation_total_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `gross_sales_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_discount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "uid": null, - "name": null, - "quantity": "quantity6", - "quantity_unit": null, - "note": null, - "catalog_object_id": null, - "variation_name": null, - "modifiers": null, - "taxes": null, - "discounts": null, - "applied_taxes": null, - "applied_discounts": null, - "base_price_money": null, - "variation_total_price_money": null, - "gross_sales_money": null, - "total_tax_money": null, - "total_discount_money": null, - "total_money": null -} -``` - +## Order Line Item + +Represents a line item in an order. Each line item describes a different +product to purchase, with its own quantity and price details. + +### Structure + +`OrderLineItem` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the line item only within this order. | +| `name` | `String` | Optional | The name of the line item. | +| `quantity` | `String` | | The quantity purchased, formatted as a decimal number.
For example: `"3"`.

Line items with a `quantity_unit` can have non-integer quantities.
For example: `"1.70000"`. | +| `quantity_unit` | [`Order Quantity Unit Hash`](/doc/models/order-quantity-unit.md) | Optional | Contains the measurement unit for a quantity and a precision which
specifies the number of digits after the decimal point for decimal quantities. | +| `note` | `String` | Optional | The note of the line item. | +| `catalog_object_id` | `String` | Optional | The [CatalogItemVariation](#type-catalogitemvariation) id applied to this line item. | +| `variation_name` | `String` | Optional | The name of the variation applied to this line item. | +| `metadata` | `Hash` | Optional | Application-defined data attached to this line item. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (personally
identifiable information, card details, etc.).

Keys written by applications must be 60 characters or less and must be in the character set
`[a-zA-Z0-9_-]`. Entries may also include metadata generated by Square. These keys are prefixed
with a namespace, separated from the key with a ':' character.

Values have a max length of 255 characters.

An application may have up to 10 entries per metadata field.

Entries written by applications are private and can only be read or modified by the same
application.

See [Metadata](https://developer.squareup.com/docs/build-basics/metadata) for more information. | +| `modifiers` | [`Array`](/doc/models/order-line-item-modifier.md) | Optional | The [CatalogModifier](#type-catalogmodifier)s applied to this line item. | +| `taxes` | [`Array`](/doc/models/order-line-item-tax.md) | Optional | A list of taxes applied to this line item. On read or retrieve, this list includes both
item-level taxes and any order-level taxes apportioned to this item. When creating an Order,
set your item-level taxes in this list.

This field has been deprecated in favour of `applied_taxes`. Usage of both this field and
`applied_taxes` when creating an order will result in an error. Usage of this field when
sending requests to the UpdateOrder endpoint will result in an error. | +| `discounts` | [`Array`](/doc/models/order-line-item-discount.md) | Optional | A list of discounts applied to this line item. On read or retrieve, this list includes
both item-level discounts and any order-level discounts apportioned to this item. When
creating an Order, set your item-level discounts in this list.

This field has been deprecated in favour of `applied_discounts`. Usage of both this field and
`applied_discounts` when creating an order will result in an error. Usage of this field when
sending requests to the UpdateOrder endpoint will result in an error. | +| `applied_taxes` | [`Array`](/doc/models/order-line-item-applied-tax.md) | Optional | The list of references to taxes applied to this line item. Each
`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a
top-level `OrderLineItemTax` applied to the line item. On reads, the
amount applied is populated.

An `OrderLineItemAppliedTax` will be automatically created on every line
item for all `ORDER` scoped taxes added to the order. `OrderLineItemAppliedTax`
records for `LINE_ITEM` scoped taxes must be added in requests for the tax
to apply to any line items.

To change the amount of a tax, modify the referenced top-level tax. | +| `applied_discounts` | [`Array`](/doc/models/order-line-item-applied-discount.md) | Optional | The list of references to discounts applied to this line item. Each
`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level
`OrderLineItemDiscounts` applied to the line item. On reads, the amount
applied is populated.

An `OrderLineItemAppliedDiscount` will be automatically created on every line item for all
`ORDER` scoped discounts that are added to the order. `OrderLineItemAppliedDiscount` records
for `LINE_ITEM` scoped discounts must be added in requests for the discount to apply to any
line items.

To change the amount of a discount, modify the referenced top-level discount. | +| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `variation_total_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `gross_sales_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_discount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "uid": null, + "name": null, + "quantity": "quantity6", + "quantity_unit": null, + "note": null, + "catalog_object_id": null, + "variation_name": null, + "metadata": null, + "modifiers": null, + "taxes": null, + "discounts": null, + "applied_taxes": null, + "applied_discounts": null, + "base_price_money": null, + "variation_total_price_money": null, + "gross_sales_money": null, + "total_tax_money": null, + "total_discount_money": null, + "total_money": null +} +``` + diff --git a/doc/models/order-money-amounts.md b/doc/models/order-money-amounts.md index 1faa1b71..e7880e71 100644 --- a/doc/models/order-money-amounts.md +++ b/doc/models/order-money-amounts.md @@ -1,30 +1,30 @@ -## Order Money Amounts - -A collection of various money amounts. - -### Structure - -`OrderMoneyAmounts` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `discount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `tip_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `service_charge_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "total_money": null, - "tax_money": null, - "discount_money": null, - "tip_money": null, - "service_charge_money": null -} -``` - +## Order Money Amounts + +A collection of various money amounts. + +### Structure + +`OrderMoneyAmounts` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `discount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `tip_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `service_charge_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "total_money": null, + "tax_money": null, + "discount_money": null, + "tip_money": null, + "service_charge_money": null +} +``` + diff --git a/doc/models/order-quantity-unit.md b/doc/models/order-quantity-unit.md index 8e31d18e..de5a5e65 100644 --- a/doc/models/order-quantity-unit.md +++ b/doc/models/order-quantity-unit.md @@ -1,25 +1,25 @@ -## Order Quantity Unit - -Contains the measurement unit for a quantity and a precision which -specifies the number of digits after the decimal point for decimal quantities. - -### Structure - -`OrderQuantityUnit` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `measurement_unit` | [`Measurement Unit Hash`](/doc/models/measurement-unit.md) | Optional | Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required: `custom_unit`,
`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`.

The `family` field describes the type of measurement. For example,
ounces are in the weight family. | -| `precision` | `Integer` | Optional | For non-integer quantities, represents the number of digits after the decimal point that are
recorded for this quantity.

For example, a precision of 1 allows quantities like `"1.0"` and `"1.1"`, but not `"1.01"`.

Min: 0. Max: 5. | - -### Example (as JSON) - -```json -{ - "measurement_unit": null, - "precision": null -} -``` - +## Order Quantity Unit + +Contains the measurement unit for a quantity and a precision which +specifies the number of digits after the decimal point for decimal quantities. + +### Structure + +`OrderQuantityUnit` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `measurement_unit` | [`Measurement Unit Hash`](/doc/models/measurement-unit.md) | Optional | Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required: `custom_unit`,
`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`. | +| `precision` | `Integer` | Optional | For non-integer quantities, represents the number of digits after the decimal point that are
recorded for this quantity.

For example, a precision of 1 allows quantities like `"1.0"` and `"1.1"`, but not `"1.01"`.

Min: 0. Max: 5. | + +### Example (as JSON) + +```json +{ + "measurement_unit": null, + "precision": null +} +``` + diff --git a/doc/models/order-return-discount.md b/doc/models/order-return-discount.md index 60447b17..35a5208a 100644 --- a/doc/models/order-return-discount.md +++ b/doc/models/order-return-discount.md @@ -1,43 +1,43 @@ -## Order Return Discount - -Represents a discount being returned that applies to one or more return line items in an -order. - -Fixed-amount, order-scoped discounts are distributed across all non-zero return line item totals. -The amount distributed to each return line item is relative to that item’s contribution to the -order subtotal. - -### Structure - -`OrderReturnDiscount` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the return discount only within this order. | -| `source_discount_uid` | `String` | Optional | `uid` of the Discount from the Order which contains the original application of this discount. | -| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogDiscount](./models/catalog-discount.md). | -| `name` | `String` | Optional | The discount's name. | -| `type` | [`String (Order Line Item Discount Type)`](/doc/models/order-line-item-discount-type.md) | Optional | Indicates how the discount is applied to the associated line item or order. | -| `percentage` | `String` | Optional | The percentage of the tax, as a string representation of a decimal number.
A value of `7.25` corresponds to a percentage of 7.25%.

The percentage won't be set for an amount-based discount. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `scope` | [`String (Order Line Item Discount Scope)`](/doc/models/order-line-item-discount-scope.md) | Optional | Indicates whether this is a line item or order level discount. | - -### Example (as JSON) - -```json -{ - "uid": null, - "source_discount_uid": null, - "catalog_object_id": null, - "name": null, - "type": null, - "percentage": null, - "amount_money": null, - "applied_money": null, - "scope": null -} -``` - +## Order Return Discount + +Represents a discount being returned that applies to one or more return line items in an +order. + +Fixed-amount, order-scoped discounts are distributed across all non-zero return line item totals. +The amount distributed to each return line item is relative to that item’s contribution to the +order subtotal. + +### Structure + +`OrderReturnDiscount` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the return discount only within this order. | +| `source_discount_uid` | `String` | Optional | `uid` of the Discount from the Order which contains the original application of this discount. | +| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogDiscount](#type-catalogdiscount). | +| `name` | `String` | Optional | The discount's name. | +| `type` | [`String (Order Line Item Discount Type)`](/doc/models/order-line-item-discount-type.md) | Optional | Indicates how the discount is applied to the associated line item or order. | +| `percentage` | `String` | Optional | The percentage of the tax, as a string representation of a decimal number.
A value of `7.25` corresponds to a percentage of 7.25%.

`percentage` is not set for amount-based discounts. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `scope` | [`String (Order Line Item Discount Scope)`](/doc/models/order-line-item-discount-scope.md) | Optional | Indicates whether this is a line item or order level discount. | + +### Example (as JSON) + +```json +{ + "uid": null, + "source_discount_uid": null, + "catalog_object_id": null, + "name": null, + "type": null, + "percentage": null, + "amount_money": null, + "applied_money": null, + "scope": null +} +``` + diff --git a/doc/models/order-return-line-item-modifier.md b/doc/models/order-return-line-item-modifier.md index a7364d1e..46ff568c 100644 --- a/doc/models/order-return-line-item-modifier.md +++ b/doc/models/order-return-line-item-modifier.md @@ -1,32 +1,32 @@ -## Order Return Line Item Modifier - -A line item modifier being returned. - -### Structure - -`OrderReturnLineItemModifier` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the return modifier only within this order. | -| `source_modifier_uid` | `String` | Optional | `uid` of the Modifier from the LineItem from the Order which contains the
original sale of this line item modifier. | -| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogModifier](./models/catalog-modifier.md). | -| `name` | `String` | Optional | The name of the item modifier. | -| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "uid": null, - "source_modifier_uid": null, - "catalog_object_id": null, - "name": null, - "base_price_money": null, - "total_price_money": null -} -``` - +## Order Return Line Item Modifier + +A line item modifier being returned. + +### Structure + +`OrderReturnLineItemModifier` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the return modifier only within this order. | +| `source_modifier_uid` | `String` | Optional | `uid` of the Modifier from the LineItem from the Order which contains the
original sale of this line item modifier. | +| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogModifier](#type-catalogmodifier). | +| `name` | `String` | Optional | The name of the item modifier. | +| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "uid": null, + "source_modifier_uid": null, + "catalog_object_id": null, + "name": null, + "base_price_money": null, + "total_price_money": null +} +``` + diff --git a/doc/models/order-return-line-item.md b/doc/models/order-return-line-item.md index 0582e404..a2d1dea8 100644 --- a/doc/models/order-return-line-item.md +++ b/doc/models/order-return-line-item.md @@ -1,58 +1,58 @@ -## Order Return Line Item - -The line item being returned in an Order. - -### Structure - -`OrderReturnLineItem` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique identifier for this return line item entry. | -| `source_line_item_uid` | `String` | Optional | `uid` of the LineItem in the original sale Order. | -| `name` | `String` | Optional | The name of the line item. | -| `quantity` | `String` | | The quantity returned, formatted as a decimal number.
For example: `"3"`.

Line items with a `quantity_unit` can have non-integer quantities.
For example: `"1.70000"`. | -| `quantity_unit` | [`Order Quantity Unit Hash`](/doc/models/order-quantity-unit.md) | Optional | Contains the measurement unit for a quantity and a precision which
specifies the number of digits after the decimal point for decimal quantities. | -| `note` | `String` | Optional | The note of the returned line item. | -| `catalog_object_id` | `String` | Optional | The [CatalogItemVariation](./models/catalog-item-variation.md) id applied to this returned line item. | -| `variation_name` | `String` | Optional | The name of the variation applied to this returned line item. | -| `return_modifiers` | [`Array`](/doc/models/order-return-line-item-modifier.md) | Optional | The [CatalogModifier](./models/catalog-modifier.md)s applied to this line item. | -| `return_taxes` | [`Array`](/doc/models/order-return-tax.md) | Optional | A list of taxes applied to this line item. On read or retrieve, this list includes both
item-level taxes and any return-level taxes apportioned to this item.

This field has been deprecated in favour of `applied_taxes`. | -| `return_discounts` | [`Array`](/doc/models/order-return-discount.md) | Optional | A list of discounts applied to this line item. On read or retrieve, this list includes
both item-level discounts and any return-level discounts apportioned to this item.

This field has been deprecated in favour of `applied_discounts`. | -| `applied_taxes` | [`Array`](/doc/models/order-line-item-applied-tax.md) | Optional | The list of references to `OrderReturnTax`s applied to this return line item. Each
`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level
`OrderReturnTax` that is being applied to this return line item. On reads, the amount applied
is populated. | -| `applied_discounts` | [`Array`](/doc/models/order-line-item-applied-discount.md) | Optional | The list of references to `OrderReturnDiscount`s applied to this return line item. Each
`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level
`OrderReturnDiscount` that is being applied to this return line item. On reads, the amount
applied is populated. | -| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `variation_total_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `gross_return_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_discount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "uid": null, - "source_line_item_uid": null, - "name": null, - "quantity": "quantity6", - "quantity_unit": null, - "note": null, - "catalog_object_id": null, - "variation_name": null, - "return_modifiers": null, - "return_taxes": null, - "return_discounts": null, - "applied_taxes": null, - "applied_discounts": null, - "base_price_money": null, - "variation_total_price_money": null, - "gross_return_money": null, - "total_tax_money": null, - "total_discount_money": null, - "total_money": null -} -``` - +## Order Return Line Item + +The line item being returned in an Order. + +### Structure + +`OrderReturnLineItem` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique identifier for this return line item entry. | +| `source_line_item_uid` | `String` | Optional | `uid` of the LineItem in the original sale Order. | +| `name` | `String` | Optional | The name of the line item. | +| `quantity` | `String` | | The quantity returned, formatted as a decimal number.
For example: `"3"`.

Line items with a `quantity_unit` can have non-integer quantities.
For example: `"1.70000"`. | +| `quantity_unit` | [`Order Quantity Unit Hash`](/doc/models/order-quantity-unit.md) | Optional | Contains the measurement unit for a quantity and a precision which
specifies the number of digits after the decimal point for decimal quantities. | +| `note` | `String` | Optional | The note of the returned line item. | +| `catalog_object_id` | `String` | Optional | The [CatalogItemVariation](#type-catalogitemvariation) id applied to this returned line item. | +| `variation_name` | `String` | Optional | The name of the variation applied to this returned line item. | +| `return_modifiers` | [`Array`](/doc/models/order-return-line-item-modifier.md) | Optional | The [CatalogModifier](#type-catalogmodifier)s applied to this line item. | +| `return_taxes` | [`Array`](/doc/models/order-return-tax.md) | Optional | A list of taxes applied to this line item. On read or retrieve, this list includes both
item-level taxes and any return-level taxes apportioned to this item.

This field has been deprecated in favour of `applied_taxes`. | +| `return_discounts` | [`Array`](/doc/models/order-return-discount.md) | Optional | A list of discounts applied to this line item. On read or retrieve, this list includes
both item-level discounts and any return-level discounts apportioned to this item.

This field has been deprecated in favour of `applied_discounts`. | +| `applied_taxes` | [`Array`](/doc/models/order-line-item-applied-tax.md) | Optional | The list of references to `OrderReturnTax` entities applied to the returned line item. Each
`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level
`OrderReturnTax` applied to the returned line item. On reads, the amount applied
is populated. | +| `applied_discounts` | [`Array`](/doc/models/order-line-item-applied-discount.md) | Optional | The list of references to `OrderReturnDiscount` entities applied to the returned line item. Each
`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level
`OrderReturnDiscount` applied to the returned line item. On reads, the amount
applied is populated. | +| `base_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `variation_total_price_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `gross_return_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_discount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "uid": null, + "source_line_item_uid": null, + "name": null, + "quantity": "quantity6", + "quantity_unit": null, + "note": null, + "catalog_object_id": null, + "variation_name": null, + "return_modifiers": null, + "return_taxes": null, + "return_discounts": null, + "applied_taxes": null, + "applied_discounts": null, + "base_price_money": null, + "variation_total_price_money": null, + "gross_return_money": null, + "total_tax_money": null, + "total_discount_money": null, + "total_money": null +} +``` + diff --git a/doc/models/order-return-service-charge.md b/doc/models/order-return-service-charge.md index add84824..b50e1d47 100644 --- a/doc/models/order-return-service-charge.md +++ b/doc/models/order-return-service-charge.md @@ -1,46 +1,46 @@ -## Order Return Service Charge - -The service charge applied to the original order. - -### Structure - -`OrderReturnServiceCharge` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the return service charge only within this order. | -| `source_service_charge_uid` | `String` | Optional | `uid` of the Service Charge from the Order which contains the original charge of this service charge,
null for unlinked returns. | -| `name` | `String` | Optional | The name of the service charge. | -| `catalog_object_id` | `String` | Optional | The ID referencing the service charge [CatalogObject](./models/catalog-object.md) | -| `percentage` | `String` | Optional | The percentage of the service charge, as a string representation of a decimal number.

A value of `7.25` corresponds to a percentage of 7.25%.

Exactly one of percentage or amount_money should be set. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `calculation_phase` | [`String (Order Service Charge Calculation Phase)`](/doc/models/order-service-charge-calculation-phase.md) | Optional | Represents a phase in the process of calculating order totals. Service charges will
be applied after the phase indicated.

[Read more about how order totals are calculated.](https://developer.squareup.com/docs/orders-api/how-it-works#how-totals-are-calculated) | -| `taxable` | `Boolean` | Optional | Indicates whether the surcharge can be taxed. Service charges calculated in the
`TOTAL_PHASE` cannot be marked as taxable. | -| `return_taxes` | [`Array`](/doc/models/order-return-tax.md) | Optional | Taxes applied to the `OrderReturnServiceCharge`. By default, return-level taxes apply to
`OrderReturnServiceCharge`s calculated in the `SUBTOTAL_PHASE` if `taxable` is set to `true`. On
read or retrieve, this list includes both item-level taxes and any return-level taxes
apportioned to this item.

This field has been deprecated in favour of `applied_taxes`. | -| `applied_taxes` | [`Array`](/doc/models/order-line-item-applied-tax.md) | Optional | The list of references to `OrderReturnTax`s applied to this `OrderReturnServiceCharge`.
Each `OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level
`OrderReturnTax` that is being applied to this `OrderReturnServiceCharge`. On reads, the amount
applied is populated. | - -### Example (as JSON) - -```json -{ - "uid": null, - "source_service_charge_uid": null, - "name": null, - "catalog_object_id": null, - "percentage": null, - "amount_money": null, - "applied_money": null, - "total_money": null, - "total_tax_money": null, - "calculation_phase": null, - "taxable": null, - "return_taxes": null, - "applied_taxes": null -} -``` - +## Order Return Service Charge + +Represents the service charge applied to the original order. + +### Structure + +`OrderReturnServiceCharge` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the return service charge only within this order. | +| `source_service_charge_uid` | `String` | Optional | `uid` of the Service Charge from the Order containing the original
charge of the service charge. `source_service_charge_uid` is `null` for
unlinked returns. | +| `name` | `String` | Optional | The name of the service charge. | +| `catalog_object_id` | `String` | Optional | The catalog object ID of the associated [CatalogServiceCharge](#type-catalogservicecharge). | +| `percentage` | `String` | Optional | The percentage of the service charge, as a string representation of
a decimal number. For example, a value of `"7.25"` corresponds to a
percentage of 7.25%.

Exactly one of `percentage` or `amount_money` should be set. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `calculation_phase` | [`String (Order Service Charge Calculation Phase)`](/doc/models/order-service-charge-calculation-phase.md) | Optional | Represents a phase in the process of calculating order totals.
Service charges are applied __after__ the indicated phase.

[Read more about how order totals are calculated.](https://developer.squareup.com/docs/docs/orders-api/how-it-works#how-totals-are-calculated) | +| `taxable` | `Boolean` | Optional | Indicates whether the surcharge can be taxed. Service charges
calculated in the `TOTAL_PHASE` cannot be marked as taxable. | +| `return_taxes` | [`Array`](/doc/models/order-return-tax.md) | Optional | Taxes applied to the `OrderReturnServiceCharge`. By default, return-level taxes apply to
`OrderReturnServiceCharge`s calculated in the `SUBTOTAL_PHASE` if `taxable` is set to `true`. On
read or retrieve, this list includes both item-level taxes and any return-level taxes
apportioned to this item.

This field has been deprecated in favour of `applied_taxes`. | +| `applied_taxes` | [`Array`](/doc/models/order-line-item-applied-tax.md) | Optional | The list of references to `OrderReturnTax` entities applied to the
`OrderReturnServiceCharge`. Each `OrderLineItemAppliedTax` has a `tax_uid`
that references the `uid` of a top-level `OrderReturnTax` that is being
applied to the `OrderReturnServiceCharge`. On reads, the amount applied is
populated. | + +### Example (as JSON) + +```json +{ + "uid": null, + "source_service_charge_uid": null, + "name": null, + "catalog_object_id": null, + "percentage": null, + "amount_money": null, + "applied_money": null, + "total_money": null, + "total_tax_money": null, + "calculation_phase": null, + "taxable": null, + "return_taxes": null, + "applied_taxes": null +} +``` + diff --git a/doc/models/order-return-tax.md b/doc/models/order-return-tax.md index 3f9bc3eb..1e713ca7 100644 --- a/doc/models/order-return-tax.md +++ b/doc/models/order-return-tax.md @@ -1,40 +1,40 @@ -## Order Return Tax - -Represents a tax being returned that applies to one or more return line items in an order. - -Fixed-amount, order-scoped taxes are distributed across all non-zero return line item totals. -The amount distributed to each return line item is relative to that item’s contribution to the -order subtotal. - -### Structure - -`OrderReturnTax` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the return tax only within this order. | -| `source_tax_uid` | `String` | Optional | `uid` of the Tax from the Order which contains the original charge of this tax. | -| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogTax](./models/catalog-tax.md). | -| `name` | `String` | Optional | The tax's name. | -| `type` | [`String (Order Line Item Tax Type)`](/doc/models/order-line-item-tax-type.md) | Optional | Indicates how the tax is applied to the associated line item or order. | -| `percentage` | `String` | Optional | The percentage of the tax, as a string representation of a decimal number.

A value of `7.25` corresponds to a percentage of 7.25%. | -| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `scope` | [`String (Order Line Item Tax Scope)`](/doc/models/order-line-item-tax-scope.md) | Optional | Indicates whether this is a line item or order level tax. | - -### Example (as JSON) - -```json -{ - "uid": null, - "source_tax_uid": null, - "catalog_object_id": null, - "name": null, - "type": null, - "percentage": null, - "applied_money": null, - "scope": null -} -``` - +## Order Return Tax + +Represents a tax being returned that applies to one or more return line items in an order. + +Fixed-amount, order-scoped taxes are distributed across all non-zero return line item totals. +The amount distributed to each return line item is relative to that item’s contribution to the +order subtotal. + +### Structure + +`OrderReturnTax` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the return tax only within this order. | +| `source_tax_uid` | `String` | Optional | `uid` of the Tax from the Order which contains the original charge of this tax. | +| `catalog_object_id` | `String` | Optional | The catalog object id referencing [CatalogTax](#type-catalogtax). | +| `name` | `String` | Optional | The tax's name. | +| `type` | [`String (Order Line Item Tax Type)`](/doc/models/order-line-item-tax-type.md) | Optional | Indicates how the tax is applied to the associated line item or order. | +| `percentage` | `String` | Optional | The percentage of the tax, as a string representation of a decimal number.
For example, a value of `"7.25"` corresponds to a percentage of 7.25%. | +| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `scope` | [`String (Order Line Item Tax Scope)`](/doc/models/order-line-item-tax-scope.md) | Optional | Indicates whether this is a line item or order level tax. | + +### Example (as JSON) + +```json +{ + "uid": null, + "source_tax_uid": null, + "catalog_object_id": null, + "name": null, + "type": null, + "percentage": null, + "applied_money": null, + "scope": null +} +``` + diff --git a/doc/models/order-return.md b/doc/models/order-return.md index e0378f01..3eeeec90 100644 --- a/doc/models/order-return.md +++ b/doc/models/order-return.md @@ -1,36 +1,36 @@ -## Order Return - -The set of line items, service charges, taxes, discounts, tips, etc. being returned in an Order. - -### Structure - -`OrderReturn` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the return only within this order. | -| `source_order_id` | `String` | Optional | Order which contains the original sale of these returned line items. This will be unset
for unlinked returns. | -| `return_line_items` | [`Array`](/doc/models/order-return-line-item.md) | Optional | Collection of line items which are being returned. | -| `return_service_charges` | [`Array`](/doc/models/order-return-service-charge.md) | Optional | Collection of service charges which are being returned. | -| `return_taxes` | [`Array`](/doc/models/order-return-tax.md) | Optional | Collection of references to taxes being returned for an order, including the total
applied tax amount to be returned. The taxes must reference a top-level tax ID from the source
order. | -| `return_discounts` | [`Array`](/doc/models/order-return-discount.md) | Optional | Collection of references to discounts being returned for an order, including the total
applied discount amount to be returned. The discounts must reference a top-level discount ID
from the source order. | -| `rounding_adjustment` | [`Order Rounding Adjustment Hash`](/doc/models/order-rounding-adjustment.md) | Optional | A rounding adjustment of the money being returned. Commonly used to apply Cash Rounding
when the minimum unit of account is smaller than the lowest physical denomination of currency. | -| `return_amounts` | [`Order Money Amounts Hash`](/doc/models/order-money-amounts.md) | Optional | A collection of various money amounts. | - -### Example (as JSON) - -```json -{ - "uid": null, - "source_order_id": null, - "return_line_items": null, - "return_service_charges": null, - "return_taxes": null, - "return_discounts": null, - "rounding_adjustment": null, - "return_amounts": null -} -``` - +## Order Return + +The set of line items, service charges, taxes, discounts, tips, etc. being returned in an Order. + +### Structure + +`OrderReturn` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the return only within this order. | +| `source_order_id` | `String` | Optional | Order which contains the original sale of these returned line items. This will be unset
for unlinked returns. | +| `return_line_items` | [`Array`](/doc/models/order-return-line-item.md) | Optional | Collection of line items which are being returned. | +| `return_service_charges` | [`Array`](/doc/models/order-return-service-charge.md) | Optional | Collection of service charges which are being returned. | +| `return_taxes` | [`Array`](/doc/models/order-return-tax.md) | Optional | Collection of references to taxes being returned for an order, including the total
applied tax amount to be returned. The taxes must reference a top-level tax ID from the source
order. | +| `return_discounts` | [`Array`](/doc/models/order-return-discount.md) | Optional | Collection of references to discounts being returned for an order, including the total
applied discount amount to be returned. The discounts must reference a top-level discount ID
from the source order. | +| `rounding_adjustment` | [`Order Rounding Adjustment Hash`](/doc/models/order-rounding-adjustment.md) | Optional | A rounding adjustment of the money being returned. Commonly used to apply Cash Rounding
when the minimum unit of account is smaller than the lowest physical denomination of currency. | +| `return_amounts` | [`Order Money Amounts Hash`](/doc/models/order-money-amounts.md) | Optional | A collection of various money amounts. | + +### Example (as JSON) + +```json +{ + "uid": null, + "source_order_id": null, + "return_line_items": null, + "return_service_charges": null, + "return_taxes": null, + "return_discounts": null, + "rounding_adjustment": null, + "return_amounts": null +} +``` + diff --git a/doc/models/order-rounding-adjustment.md b/doc/models/order-rounding-adjustment.md index a26d3e85..bfda3779 100644 --- a/doc/models/order-rounding-adjustment.md +++ b/doc/models/order-rounding-adjustment.md @@ -1,27 +1,27 @@ -## Order Rounding Adjustment - -A rounding adjustment of the money being returned. Commonly used to apply Cash Rounding -when the minimum unit of account is smaller than the lowest physical denomination of currency. - -### Structure - -`OrderRoundingAdjustment` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the rounding adjustment only within this order. | -| `name` | `String` | Optional | The name of the rounding adjustment from the original sale Order. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "uid": null, - "name": null, - "amount_money": null -} -``` - +## Order Rounding Adjustment + +A rounding adjustment of the money being returned. Commonly used to apply Cash Rounding +when the minimum unit of account is smaller than the lowest physical denomination of currency. + +### Structure + +`OrderRoundingAdjustment` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the rounding adjustment only within this order. | +| `name` | `String` | Optional | The name of the rounding adjustment from the original sale Order. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "uid": null, + "name": null, + "amount_money": null +} +``` + diff --git a/doc/models/order-service-charge-calculation-phase.md b/doc/models/order-service-charge-calculation-phase.md index ed71f490..23a8f858 100644 --- a/doc/models/order-service-charge-calculation-phase.md +++ b/doc/models/order-service-charge-calculation-phase.md @@ -1,18 +1,18 @@ -## Order Service Charge Calculation Phase - -Represents a phase in the process of calculating order totals. Service charges will -be applied after the phase indicated. +## Order Service Charge Calculation Phase + +Represents a phase in the process of calculating order totals. +Service charges are applied __after__ the indicated phase. + +[Read more about how order totals are calculated.](https://developer.squareup.com/docs/docs/orders-api/how-it-works#how-totals-are-calculated) + +### Enumeration + +`OrderServiceChargeCalculationPhase` + +### Fields + +| Name | Description | +| --- | --- | +| `SUBTOTAL_PHASE` | The service charge will be applied after discounts, but before
taxes. | +| `TOTAL_PHASE` | The service charge will be applied after all discounts and taxes
are applied. | -[Read more about how order totals are calculated.](https://developer.squareup.com/docs/orders-api/how-it-works#how-totals-are-calculated) - -### Enumeration - -`OrderServiceChargeCalculationPhase` - -### Fields - -| Name | Description | -| --- | --- | -| `SUBTOTAL_PHASE` | The service charge will be applied after discounts but before taxes. | -| `TOTAL_PHASE` | The service charge will be applied after both discounts and taxes are applied. | - diff --git a/doc/models/order-service-charge.md b/doc/models/order-service-charge.md index 6234a7d3..b1705193 100644 --- a/doc/models/order-service-charge.md +++ b/doc/models/order-service-charge.md @@ -1,44 +1,46 @@ -## Order Service Charge - -Represents a service charge applied to an order. - -### Structure - -`OrderServiceCharge` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `uid` | `String` | Optional | Unique ID that identifies the service charge only within this order. | -| `name` | `String` | Optional | The name of the service charge. | -| `catalog_object_id` | `String` | Optional | The catalog object ID referencing the service charge [CatalogObject](./models/catalog-object.md). | -| `percentage` | `String` | Optional | The service charge percentage, as a string representation of a decimal number.

For example, `7.25` indicates 7.25%

Exactly one of `percentage` or `amount_money` should be set. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `calculation_phase` | [`String (Order Service Charge Calculation Phase)`](/doc/models/order-service-charge-calculation-phase.md) | Optional | Represents a phase in the process of calculating order totals. Service charges will
be applied after the phase indicated.

[Read more about how order totals are calculated.](https://developer.squareup.com/docs/orders-api/how-it-works#how-totals-are-calculated) | -| `taxable` | `Boolean` | Optional | Indicates whether the service charge can be taxed. If set to `true`, any order-level
taxes will automatically apply to this service charge. Note that service charges calculated
in the `TOTAL_PHASE` cannot be marked as taxable. | -| `taxes` | [`Array`](/doc/models/order-line-item-tax.md) | Optional | A list of taxes applied to this service charge. On read or retrieve, this list includes
both item-level taxes and any order-level taxes apportioned to this service charge.
When creating an Order, set your service charge-level taxes in this list. By default,
order-level taxes apply to service charges calculated in the `SUBTOTAL_PHASE` if `taxable` is
set to `true`.

This field has been deprecated in favour of `applied_taxes`. Usage of both this field and
`applied_taxes` when creating an order will result in an error. Usage of this field when
sending requests to the UpdateOrder endpoint will result in an error. | -| `applied_taxes` | [`Array`](/doc/models/order-line-item-applied-tax.md) | Optional | The list of references to taxes applied to this service charge. Each
`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level
`OrderLineItemTax` that is being applied to this service charge. On reads, the amount applied
is populated.

An `OrderLineItemAppliedTax` will be automatically created on every taxable service charge
for all `ORDER` scoped taxes that are added to the order. `OrderLineItemAppliedTax` records
for `LINE_ITEM` scoped taxes must be added in requests for the tax to apply to any taxable
service charge. Taxable service charges have the `taxable` field set to true and calculated
in the `SUBTOTAL_PHASE`.

To change the amount of a tax, modify the referenced top-level tax. | - -### Example (as JSON) - -```json -{ - "uid": null, - "name": null, - "catalog_object_id": null, - "percentage": null, - "amount_money": null, - "applied_money": null, - "total_money": null, - "total_tax_money": null, - "calculation_phase": null, - "taxable": null, - "taxes": null, - "applied_taxes": null -} -``` - +## Order Service Charge + +Represents a service charge applied to an order. + +### Structure + +`OrderServiceCharge` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `uid` | `String` | Optional | Unique ID that identifies the service charge only within this order. | +| `name` | `String` | Optional | The name of the service charge. | +| `catalog_object_id` | `String` | Optional | The catalog object ID referencing the service charge [CatalogObject](#type-catalogobject). | +| `percentage` | `String` | Optional | The service charge percentage as a string representation of a
decimal number. For example, `"7.25"` indicates a service charge of 7.25%.

Exactly 1 of `percentage` or `amount_money` should be set. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `applied_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `calculation_phase` | [`String (Order Service Charge Calculation Phase)`](/doc/models/order-service-charge-calculation-phase.md) | Optional | Represents a phase in the process of calculating order totals.
Service charges are applied __after__ the indicated phase.

[Read more about how order totals are calculated.](https://developer.squareup.com/docs/docs/orders-api/how-it-works#how-totals-are-calculated) | +| `taxable` | `Boolean` | Optional | Indicates whether the service charge can be taxed. If set to `true`,
order-level taxes automatically apply to the service charge. Note that
service charges calculated in the `TOTAL_PHASE` cannot be marked as taxable. | +| `taxes` | [`Array`](/doc/models/order-line-item-tax.md) | Optional | A list of taxes applied to this service charge. On read or retrieve, this list includes
both item-level taxes and any order-level taxes apportioned to this service charge.
When creating an Order, set your service charge-level taxes in this list. By default,
order-level taxes apply to service charges calculated in the `SUBTOTAL_PHASE` if `taxable` is
set to `true`.

This field has been deprecated in favour of `applied_taxes`. Usage of both this field and
`applied_taxes` when creating an order will result in an error. Usage of this field when
sending requests to the UpdateOrder endpoint will result in an error. | +| `applied_taxes` | [`Array`](/doc/models/order-line-item-applied-tax.md) | Optional | The list of references to taxes applied to this service charge. Each
`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level
`OrderLineItemTax` that is being applied to this service charge. On reads, the amount applied
is populated.

An `OrderLineItemAppliedTax` will be automatically created on every taxable service charge
for all `ORDER` scoped taxes that are added to the order. `OrderLineItemAppliedTax` records
for `LINE_ITEM` scoped taxes must be added in requests for the tax to apply to any taxable
service charge. Taxable service charges have the `taxable` field set to true and calculated
in the `SUBTOTAL_PHASE`.

To change the amount of a tax, modify the referenced top-level tax. | +| `metadata` | `Hash` | Optional | Application-defined data attached to this service charge. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (personally
identifiable information, card details, etc.).

Keys written by applications must be 60 characters or less and must be in the character set
`[a-zA-Z0-9_-]`. Entries may also include metadata generated by Square. These keys are prefixed
with a namespace, separated from the key with a ':' character.

Values have a max length of 255 characters.

An application may have up to 10 entries per metadata field.

Entries written by applications are private and can only be read or modified by the same
application.

See [Metadata](https://developer.squareup.com/docs/build-basics/metadata) for more information. | + +### Example (as JSON) + +```json +{ + "uid": null, + "name": null, + "catalog_object_id": null, + "percentage": null, + "amount_money": null, + "applied_money": null, + "total_money": null, + "total_tax_money": null, + "calculation_phase": null, + "taxable": null, + "taxes": null, + "applied_taxes": null, + "metadata": null +} +``` + diff --git a/doc/models/order-source.md b/doc/models/order-source.md index b693dff0..d8f71997 100644 --- a/doc/models/order-source.md +++ b/doc/models/order-source.md @@ -1,22 +1,22 @@ -## Order Source - -Represents the origination details of an order. - -### Structure - -`OrderSource` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The name used to identify the place (physical or digital) that an order originates.
If unset, the name defaults to the name of the application that created the order. | - -### Example (as JSON) - -```json -{ - "name": null -} -``` - +## Order Source + +Represents the origination details of an order. + +### Structure + +`OrderSource` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The name used to identify the place (physical or digital) that an order originates.
If unset, the name defaults to the name of the application that created the order. | + +### Example (as JSON) + +```json +{ + "name": null +} +``` + diff --git a/doc/models/order-state.md b/doc/models/order-state.md index 5823192b..8282d2ea 100644 --- a/doc/models/order-state.md +++ b/doc/models/order-state.md @@ -1,16 +1,16 @@ -## Order State - -The state of the order. - -### Enumeration - -`OrderState` - -### Fields - -| Name | Description | -| --- | --- | -| `OPEN` | Indicates the order is open. Open orders may be updated. | -| `COMPLETED` | Indicates the order is completed. Completed orders are fully paid. This is a terminal state. | -| `CANCELED` | Indicates the order is canceled. Canceled orders are not paid. This is a terminal state. | - +## Order State + +The state of the order. + +### Enumeration + +`OrderState` + +### Fields + +| Name | Description | +| --- | --- | +| `OPEN` | Indicates the order is open. Open orders may be updated. | +| `COMPLETED` | Indicates the order is completed. Completed orders are fully paid. This is a terminal state. | +| `CANCELED` | Indicates the order is canceled. Canceled orders are not paid. This is a terminal state. | + diff --git a/doc/models/order.md b/doc/models/order.md index eb580b18..8dfea969 100644 --- a/doc/models/order.md +++ b/doc/models/order.md @@ -1,75 +1,77 @@ -## Order - -Contains all information related to a single order to process with Square, -including line items that specify the products to purchase. Order objects also -include information on any associated tenders, refunds, and returns. - -All Connect V2 Transactions have all been converted to Orders including all associated -itemization data. - -### Structure - -`Order` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The order's unique ID. | -| `location_id` | `String` | | The ID of the merchant location this order is associated with. | -| `reference_id` | `String` | Optional | A client specified identifier to associate an entity in another system
with this order. | -| `source` | [`Order Source Hash`](/doc/models/order-source.md) | Optional | Represents the origination details of an order. | -| `customer_id` | `String` | Optional | The [Customer](./models/customer.md) ID of the customer associated with the order. | -| `line_items` | [`Array`](/doc/models/order-line-item.md) | Optional | The line items included in the order. | -| `taxes` | [`Array`](/doc/models/order-line-item-tax.md) | Optional | The list of all taxes applied to this order.

Taxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an
`OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes
with `ORDER` scope, the server will generate an `OrderLineItemAppliedTax` for every line item.

On reads, each tax in the list will include the total amount of that tax applied to the order.

If `LINE_ITEM` scope is set on any taxes in this field, usage of the deprecated
`line_items.taxes` field will result in an error. Please use `line_items.applied_taxes`
instead. | -| `discounts` | [`Array`](/doc/models/order-line-item-discount.md) | Optional | The list of all discounts applied to this order.

Discounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`,
an `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to.
For discounts with `ORDER` scope, the server will generate an `OrderLineItemAppliedDiscount`
for every line item.

If `LINE_ITEM` scope is set on any discounts in this field, usage of the deprecated
`line_items.discounts` field will result in an error. Please use `line_items.applied_discounts`
instead. | -| `service_charges` | [`Array`](/doc/models/order-service-charge.md) | Optional | A list of service charges applied to the order. | -| `fulfillments` | [`Array`](/doc/models/order-fulfillment.md) | Optional | Details on order fulfillment.

Orders can only be created with at most one fulfillment. However, orders returned
by the API may contain multiple fulfillments. | -| `returns` | [`Array`](/doc/models/order-return.md) | Optional | Collection of items from sale Orders being returned in this one. Normally part of an
Itemized Return or Exchange. There will be exactly one `Return` object per sale Order being
referenced. | -| `return_amounts` | [`Order Money Amounts Hash`](/doc/models/order-money-amounts.md) | Optional | A collection of various money amounts. | -| `net_amounts` | [`Order Money Amounts Hash`](/doc/models/order-money-amounts.md) | Optional | A collection of various money amounts. | -| `rounding_adjustment` | [`Order Rounding Adjustment Hash`](/doc/models/order-rounding-adjustment.md) | Optional | A rounding adjustment of the money being returned. Commonly used to apply Cash Rounding
when the minimum unit of account is smaller than the lowest physical denomination of currency. | -| `tenders` | [`Array`](/doc/models/tender.md) | Optional | The Tenders which were used to pay for the Order. | -| `refunds` | [`Array`](/doc/models/refund.md) | Optional | The Refunds that are part of this Order. | -| `created_at` | `String` | Optional | Timestamp for when the order was created. In RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | -| `updated_at` | `String` | Optional | Timestamp for when the order was last updated. In RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | -| `closed_at` | `String` | Optional | Timestamp for when the order was closed. In RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | -| `state` | [`String (Order State)`](/doc/models/order-state.md) | Optional | The state of the order. | -| `version` | `Integer` | Optional | Monotonically increasing version, incremented each time an update is committed to the order.
Orders that were not created through the API are not updatable and thus will not include a
version. | -| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_discount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_service_charge_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "id": null, - "location_id": "location_id4", - "reference_id": null, - "source": null, - "customer_id": null, - "line_items": null, - "taxes": null, - "discounts": null, - "service_charges": null, - "fulfillments": null, - "returns": null, - "return_amounts": null, - "net_amounts": null, - "rounding_adjustment": null, - "tenders": null, - "refunds": null, - "created_at": null, - "updated_at": null, - "closed_at": null, - "state": null, - "version": null, - "total_money": null, - "total_tax_money": null, - "total_discount_money": null, - "total_service_charge_money": null -} -``` - +## Order + +Contains all information related to a single order to process with Square, +including line items that specify the products to purchase. Order objects also +include information on any associated tenders, refunds, and returns. + +All Connect V2 Transactions have all been converted to Orders including all associated +itemization data. + +### Structure + +`Order` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The order's unique ID. | +| `location_id` | `String` | | The ID of the merchant location this order is associated with. | +| `reference_id` | `String` | Optional | A client specified identifier to associate an entity in another system
with this order. | +| `source` | [`Order Source Hash`](/doc/models/order-source.md) | Optional | Represents the origination details of an order. | +| `customer_id` | `String` | Optional | The [Customer](#type-customer) ID of the customer associated with the order. | +| `line_items` | [`Array`](/doc/models/order-line-item.md) | Optional | The line items included in the order. | +| `taxes` | [`Array`](/doc/models/order-line-item-tax.md) | Optional | The list of all taxes associated with the order.

Taxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an
`OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes
with `ORDER` scope, the server will generate an `OrderLineItemAppliedTax` for every line item.

On reads, each tax in the list will include the total amount of that tax applied to the order.

__IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, usage of the deprecated
`line_items.taxes` field will result in an error. Please use `line_items.applied_taxes`
instead. | +| `discounts` | [`Array`](/doc/models/order-line-item-discount.md) | Optional | The list of all discounts associated with the order.

Discounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`,
an `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to.
For discounts with `ORDER` scope, the server will generate an `OrderLineItemAppliedDiscount`
for every line item.

__IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, usage of the deprecated
`line_items.discounts` field will result in an error. Please use `line_items.applied_discounts`
instead. | +| `service_charges` | [`Array`](/doc/models/order-service-charge.md) | Optional | A list of service charges applied to the order. | +| `fulfillments` | [`Array`](/doc/models/order-fulfillment.md) | Optional | Details on order fulfillment.

Orders can only be created with at most one fulfillment. However, orders returned
by the API may contain multiple fulfillments. | +| `returns` | [`Array`](/doc/models/order-return.md) | Optional | Collection of items from sale Orders being returned in this one. Normally part of an
Itemized Return or Exchange. There will be exactly one `Return` object per sale Order being
referenced. | +| `return_amounts` | [`Order Money Amounts Hash`](/doc/models/order-money-amounts.md) | Optional | A collection of various money amounts. | +| `net_amounts` | [`Order Money Amounts Hash`](/doc/models/order-money-amounts.md) | Optional | A collection of various money amounts. | +| `rounding_adjustment` | [`Order Rounding Adjustment Hash`](/doc/models/order-rounding-adjustment.md) | Optional | A rounding adjustment of the money being returned. Commonly used to apply Cash Rounding
when the minimum unit of account is smaller than the lowest physical denomination of currency. | +| `tenders` | [`Array`](/doc/models/tender.md) | Optional | The Tenders which were used to pay for the Order. | +| `refunds` | [`Array`](/doc/models/refund.md) | Optional | The Refunds that are part of this Order. | +| `metadata` | `Hash` | Optional | Application-defined data attached to this order. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (personally
identifiable information, card details, etc.).

Keys written by applications must be 60 characters or less and must be in the character set
`[a-zA-Z0-9_-]`. Entries may also include metadata generated by Square. These keys are prefixed
with a namespace, separated from the key with a ':' character.

Values have a max length of 255 characters.

An application may have up to 10 entries per metadata field.

Entries written by applications are private and can only be read or modified by the same
application.

See [Metadata](https://developer.squareup.com/docs/build-basics/metadata) for more information. | +| `created_at` | `String` | Optional | Timestamp for when the order was created. In RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | +| `updated_at` | `String` | Optional | Timestamp for when the order was last updated. In RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | +| `closed_at` | `String` | Optional | Timestamp for when the order was closed. In RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | +| `state` | [`String (Order State)`](/doc/models/order-state.md) | Optional | The state of the order. | +| `version` | `Integer` | Optional | Version number which is incremented each time an update is committed to the order.
Orders that were not created through the API will not include a version and
thus cannot be updated.

[Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders#update-orders). | +| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_tax_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_discount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_service_charge_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "id": null, + "location_id": "location_id4", + "reference_id": null, + "source": null, + "customer_id": null, + "line_items": null, + "taxes": null, + "discounts": null, + "service_charges": null, + "fulfillments": null, + "returns": null, + "return_amounts": null, + "net_amounts": null, + "rounding_adjustment": null, + "tenders": null, + "refunds": null, + "metadata": null, + "created_at": null, + "updated_at": null, + "closed_at": null, + "state": null, + "version": null, + "total_money": null, + "total_tax_money": null, + "total_discount_money": null, + "total_service_charge_money": null +} +``` + diff --git a/doc/models/pay-order-request.md b/doc/models/pay-order-request.md index 229433d7..804a1ba7 100644 --- a/doc/models/pay-order-request.md +++ b/doc/models/pay-order-request.md @@ -1,29 +1,29 @@ -## Pay Order Request - +## Pay Order Request + Defines the fields that are included in requests to the -[PayOrder](#endpoint-payorder) endpoint. - -### Structure - -`PayOrderRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `idempotency_key` | `String` | | A value you specify that uniquely identifies this request among requests you've sent. If
you're unsure whether a particular payment request was completed successfully, you can reattempt
it with the same idempotency key without worrying about duplicate payments.

See [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency) for more information. | -| `order_version` | `Integer` | Optional | The version of the order being paid. If not supplied, the latest version will be paid. | -| `payment_ids` | `Array` | Optional | - | - -### Example (as JSON) - -```json -{ - "idempotency_key": "c043a359-7ad9-4136-82a9-c3f1d66dcbff", - "payment_ids": [ - "EnZdNAlWCmfh6Mt5FMNST1o7taB", - "0LRiVlbXVwe8ozu4KbZxd12mvaB" - ] -} -``` - +[PayOrder](#endpoint-payorder) endpoint. + +### Structure + +`PayOrderRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `String` | | A value you specify that uniquely identifies this request among requests you've sent. If
you're unsure whether a particular payment request was completed successfully, you can reattempt
it with the same idempotency key without worrying about duplicate payments.

See [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency) for more information. | +| `order_version` | `Integer` | Optional | The version of the order being paid. If not supplied, the latest version will be paid. | +| `payment_ids` | `Array` | Optional | - | + +### Example (as JSON) + +```json +{ + "idempotency_key": "c043a359-7ad9-4136-82a9-c3f1d66dcbff", + "payment_ids": [ + "EnZdNAlWCmfh6Mt5FMNST1o7taB", + "0LRiVlbXVwe8ozu4KbZxd12mvaB" + ] +} +``` + diff --git a/doc/models/pay-order-response.md b/doc/models/pay-order-response.md index f8211280..60e589d9 100644 --- a/doc/models/pay-order-response.md +++ b/doc/models/pay-order-response.md @@ -1,179 +1,173 @@ -## Pay Order Response - -Defines the fields that are included in the response body of a request to the -[PayOrder](#endpoint-payorder) endpoint. - -### Structure - -`PayOrderResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | - -### Example (as JSON) - -```json -{ - "order": { - "id": "lgwOlEityYPJtcuvKTVKT1pA986YY", - "location_id": "P3CCK6HSNDAS7", - "line_items": [ - { - "uid": "QW6kofLHJK7JEKMjlSVP5C", - "quantity": "1", - "name": "Item 1", - "base_price_money": { - "amount": 500, - "currency": "USD" - }, - "gross_sales_money": { - "amount": 500, - "currency": "USD" - }, - "total_tax_money": { - "amount": 0, - "currency": "USD" - }, - "total_discount_money": { - "amount": 0, - "currency": "USD" - }, - "total_money": { - "amount": 500, - "currency": "USD" - } - }, - { - "uid": "zhw8MNfRGdFQMI2WE1UBJD", - "quantity": "2", - "name": "Item 2", - "base_price_money": { - "amount": 750, - "currency": "USD" - }, - "gross_sales_money": { - "amount": 1500, - "currency": "USD" - }, - "total_tax_money": { - "amount": 0, - "currency": "USD" - }, - "total_discount_money": { - "amount": 0, - "currency": "USD" - }, - "total_money": { - "amount": 1500, - "currency": "USD" - } - } - ], - "created_at": "2019-08-06T02:47:35.693Z", - "updated_at": "2019-08-06T02:47:37.140Z", - "version": 4, - "total_tax_money": { - "amount": 0, - "currency": "USD" - }, - "total_discount_money": { - "amount": 0, - "currency": "USD" - }, - "total_tip_money": { - "amount": 0, - "currency": "USD" - }, - "total_money": { - "amount": 2000, - "currency": "USD" - }, - "closed_at": "2019-08-06T02:47:37.140Z", - "tenders": [ - { - "id": "EnZdNAlWCmfh6Mt5FMNST1o7taB", - "location_id": "P3CCK6HSNDAS7", - "transaction_id": "lgwOlEityYPJtcuvKTVKT1pA986YY", - "created_at": "2019-08-06T02:47:36.293Z", - "amount_money": { - "amount": 1000, - "currency": "USD" - }, - "type": "CARD", - "card_details": { - "status": "CAPTURED", - "card": { - "card_brand": "VISA", - "last_4": "1111", - "exp_month": 2, - "exp_year": 2022, - "fingerprint": "sq-1-n_BL15KP87ClDa4-h2nXOI0fp5VnxNH6hfhzqhptTfAgxgLuGFcg6jIPngDz4IkkTQ", - "bin": "411111" - }, - "entry_method": "KEYED" - }, - "payment_id": "EnZdNAlWCmfh6Mt5FMNST1o7taB" - }, - { - "id": "0LRiVlbXVwe8ozu4KbZxd12mvaB", - "location_id": "P3CCK6HSNDAS7", - "transaction_id": "lgwOlEityYPJtcuvKTVKT1pA986YY", - "created_at": "2019-08-06T02:47:36.809Z", - "amount_money": { - "amount": 1000, - "currency": "USD" - }, - "type": "CARD", - "card_details": { - "status": "CAPTURED", - "card": { - "card_brand": "VISA", - "last_4": "1111", - "exp_month": 2, - "exp_year": 2022, - "fingerprint": "sq-1-n_BL15KP87ClDa4-h2nXOI0fp5VnxNH6hfhzqhptTfAgxgLuGFcg6jIPngDz4IkkTQ", - "bin": "411111" - }, - "entry_method": "KEYED" - }, - "payment_id": "0LRiVlbXVwe8ozu4KbZxd12mvaB" - } - ], - "total_service_charge_money": { - "amount": 0, - "currency": "USD" - }, - "net_amounts": { - "total_money": { - "amount": 2000, - "currency": "USD" - }, - "tax_money": { - "amount": 0, - "currency": "USD" - }, - "discount_money": { - "amount": 0, - "currency": "USD" - }, - "tip_money": { - "amount": 0, - "currency": "USD" - }, - "service_charge_money": { - "amount": 0, - "currency": "USD" - } - }, - "source": { - "name": "Source Name" - }, - "status": "COMPLETED" - } -} -``` - +## Pay Order Response + +Defines the fields that are included in the response body of a request to the +[PayOrder](#endpoint-payorder) endpoint. + +### Structure + +`PayOrderResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | + +### Example (as JSON) + +```json +{ + "order": { + "id": "lgwOlEityYPJtcuvKTVKT1pA986YY", + "location_id": "P3CCK6HSNDAS7", + "line_items": [ + { + "uid": "QW6kofLHJK7JEKMjlSVP5C", + "quantity": "1", + "name": "Item 1", + "base_price_money": { + "amount": 500, + "currency": "USD" + }, + "gross_sales_money": { + "amount": 500, + "currency": "USD" + }, + "total_tax_money": { + "amount": 0, + "currency": "USD" + }, + "total_discount_money": { + "amount": 0, + "currency": "USD" + }, + "total_money": { + "amount": 500, + "currency": "USD" + } + }, + { + "uid": "zhw8MNfRGdFQMI2WE1UBJD", + "quantity": "2", + "name": "Item 2", + "base_price_money": { + "amount": 750, + "currency": "USD" + }, + "gross_sales_money": { + "amount": 1500, + "currency": "USD" + }, + "total_tax_money": { + "amount": 0, + "currency": "USD" + }, + "total_discount_money": { + "amount": 0, + "currency": "USD" + }, + "total_money": { + "amount": 1500, + "currency": "USD" + } + } + ], + "created_at": "2019-08-06T02:47:35.693Z", + "updated_at": "2019-08-06T02:47:37.140Z", + "version": 4, + "total_tax_money": { + "amount": 0, + "currency": "USD" + }, + "total_discount_money": { + "amount": 0, + "currency": "USD" + }, + "total_money": { + "amount": 2000, + "currency": "USD" + }, + "closed_at": "2019-08-06T02:47:37.140Z", + "tenders": [ + { + "id": "EnZdNAlWCmfh6Mt5FMNST1o7taB", + "location_id": "P3CCK6HSNDAS7", + "transaction_id": "lgwOlEityYPJtcuvKTVKT1pA986YY", + "created_at": "2019-08-06T02:47:36.293Z", + "amount_money": { + "amount": 1000, + "currency": "USD" + }, + "type": "CARD", + "card_details": { + "status": "CAPTURED", + "card": { + "card_brand": "VISA", + "last_4": "1111", + "exp_month": 2, + "exp_year": 2022, + "fingerprint": "sq-1-n_BL15KP87ClDa4-h2nXOI0fp5VnxNH6hfhzqhptTfAgxgLuGFcg6jIPngDz4IkkTQ" + }, + "entry_method": "KEYED" + }, + "payment_id": "EnZdNAlWCmfh6Mt5FMNST1o7taB" + }, + { + "id": "0LRiVlbXVwe8ozu4KbZxd12mvaB", + "location_id": "P3CCK6HSNDAS7", + "transaction_id": "lgwOlEityYPJtcuvKTVKT1pA986YY", + "created_at": "2019-08-06T02:47:36.809Z", + "amount_money": { + "amount": 1000, + "currency": "USD" + }, + "type": "CARD", + "card_details": { + "status": "CAPTURED", + "card": { + "card_brand": "VISA", + "last_4": "1111", + "exp_month": 2, + "exp_year": 2022, + "fingerprint": "sq-1-n_BL15KP87ClDa4-h2nXOI0fp5VnxNH6hfhzqhptTfAgxgLuGFcg6jIPngDz4IkkTQ" + }, + "entry_method": "KEYED" + }, + "payment_id": "0LRiVlbXVwe8ozu4KbZxd12mvaB" + } + ], + "total_service_charge_money": { + "amount": 0, + "currency": "USD" + }, + "net_amounts": { + "total_money": { + "amount": 2000, + "currency": "USD" + }, + "tax_money": { + "amount": 0, + "currency": "USD" + }, + "discount_money": { + "amount": 0, + "currency": "USD" + }, + "tip_money": { + "amount": 0, + "currency": "USD" + }, + "service_charge_money": { + "amount": 0, + "currency": "USD" + } + }, + "source": { + "name": "Source Name" + }, + "state": "COMPLETED" + } +} +``` + diff --git a/doc/models/payment-refund.md b/doc/models/payment-refund.md index cca44cab..225ae70a 100644 --- a/doc/models/payment-refund.md +++ b/doc/models/payment-refund.md @@ -1,44 +1,46 @@ -## Payment Refund - -Represents a refund of a payment made using Square. Contains information on -the original payment and the amount of money refunded. - -### Structure - -`PaymentRefund` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | | Unique ID for this refund, generated by Square. | -| `status` | `String` | Optional | The refund's status:
- `PENDING` - awaiting approval
- `COMPLETED` - successfully completed
- `REJECTED` - the refund was rejected
- `FAILED` - an error occurred | -| `location_id` | `String` | Optional | Location ID associated with the payment this refund is attached to. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `app_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `processing_fee` | [`Array`](/doc/models/processing-fee.md) | Optional | Processing fees and fee adjustments assessed by Square on this refund. | -| `payment_id` | `String` | Optional | The ID of the payment assocated with this refund. | -| `reason` | `String` | Optional | The reason for the refund. | -| `created_at` | `String` | Optional | Timestamp of when the refund was created, in RFC 3339 format. | -| `updated_at` | `String` | Optional | Timestamp of when the refund was last updated, in RFC 3339 format. | - -### Example (as JSON) - -```json -{ - "id": "id0", - "status": null, - "location_id": null, - "amount_money": { - "amount": null, - "currency": null - }, - "app_fee_money": null, - "processing_fee": null, - "payment_id": null, - "reason": null, - "created_at": null, - "updated_at": null -} -``` - +## Payment Refund + +Represents a refund of a payment made using Square. Contains information on +the original payment and the amount of money refunded. + +### Structure + +`PaymentRefund` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | | Unique ID for this refund, generated by Square. | +| `status` | `String` | Optional | The refund's status:
- `PENDING` - awaiting approval
- `COMPLETED` - successfully completed
- `REJECTED` - the refund was rejected
- `FAILED` - an error occurred | +| `location_id` | `String` | Optional | Location ID associated with the payment this refund is attached to. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `app_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `processing_fee` | [`Array`](/doc/models/processing-fee.md) | Optional | Processing fees and fee adjustments assessed by Square on this refund. | +| `payment_id` | `String` | Optional | The ID of the payment assocated with this refund. | +| `order_id` | `String` | Optional | The ID of the order associated with the refund. | +| `reason` | `String` | Optional | The reason for the refund. | +| `created_at` | `String` | Optional | Timestamp of when the refund was created, in RFC 3339 format. | +| `updated_at` | `String` | Optional | Timestamp of when the refund was last updated, in RFC 3339 format. | + +### Example (as JSON) + +```json +{ + "id": "id0", + "status": null, + "location_id": null, + "amount_money": { + "amount": null, + "currency": null + }, + "app_fee_money": null, + "processing_fee": null, + "payment_id": null, + "order_id": null, + "reason": null, + "created_at": null, + "updated_at": null +} +``` + diff --git a/doc/models/payment.md b/doc/models/payment.md index 911a05e7..bf8a7385 100644 --- a/doc/models/payment.md +++ b/doc/models/payment.md @@ -1,65 +1,64 @@ -## Payment - -Represents a payment processed by the Square API. - -### Structure - -`Payment` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | | Unique ID for the payment. | -| `created_at` | `String` | Optional | Timestamp of when the payment was created, in RFC 3339 format. | -| `updated_at` | `String` | Optional | Timestamp of when the payment was last updated, in RFC 3339 format. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `tip_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `app_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `processing_fee` | [`Array`](/doc/models/processing-fee.md) | Optional | Processing fees and fee adjustments assessed by Square on this payment. | -| `refunded_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `status` | `String` | Optional | Indicates whether the payment is `APPROVED`, `COMPLETED`, `CANCELED`, or `FAILED`. | -| `source_type` | `String` | Optional | The source type for this payment | -| `card_details` | [`Card Payment Details Hash`](/doc/models/card-payment-details.md) | Optional | Reflects the current status of a card payment. | -| `location_id` | `String` | Optional | ID of the location associated with the payment. | -| `order_id` | `String` | Optional | ID of the order associated with this payment. | -| `reference_id` | `String` | Optional | An optional ID that associates this payment with an entity in
another system. | -| `customer_id` | `String` | Optional | An optional customer_id to be entered by the developer when creating a payment. | -| `refund_ids` | `Array` | Optional | List of `refund_id`s identifying refunds for this payment. | -| `buyer_email_address` | `String` | Optional | The buyer's e-mail address | -| `billing_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `note` | `String` | Optional | An optional note to include when creating a payment | - -### Example (as JSON) - -```json -{ - "id": "id0", - "created_at": null, - "updated_at": null, - "amount_money": { - "amount": null, - "currency": null - }, - "tip_money": null, - "total_money": null, - "app_fee_money": null, - "processing_fee": null, - "refunded_money": null, - "status": null, - "source_type": null, - "card_details": null, - "location_id": null, - "order_id": null, - "reference_id": null, - "customer_id": null, - "refund_ids": null, - "buyer_email_address": null, - "billing_address": null, - "shipping_address": null, - "note": null -} -``` - +## Payment + +Represents a payment processed by the Square API. + +### Structure + +`Payment` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | Unique ID for the payment. | +| `created_at` | `String` | Optional | Timestamp of when the payment was created, in RFC 3339 format. | +| `updated_at` | `String` | Optional | Timestamp of when the payment was last updated, in RFC 3339 format. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `tip_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `total_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `app_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `processing_fee` | [`Array`](/doc/models/processing-fee.md) | Optional | Processing fees and fee adjustments assessed by Square on this payment. | +| `refunded_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `status` | `String` | Optional | Indicates whether the payment is `APPROVED`, `COMPLETED`, `CANCELED`, or `FAILED`. | +| `source_type` | `String` | Optional | The source type for this payment

Current values include:
`CARD` | +| `card_details` | [`Card Payment Details Hash`](/doc/models/card-payment-details.md) | Optional | Reflects the current status of a card payment. | +| `location_id` | `String` | Optional | ID of the location associated with the payment. | +| `order_id` | `String` | Optional | ID of the order associated with this payment. | +| `reference_id` | `String` | Optional | An optional ID that associates this payment with an entity in
another system. | +| `customer_id` | `String` | Optional | An optional customer_id to be entered by the developer when creating a payment. | +| `employee_id` | `String` | Optional | An optional ID of the employee associated with taking this payment. | +| `refund_ids` | `Array` | Optional | List of `refund_id`s identifying refunds for this payment. | +| `buyer_email_address` | `String` | Optional | The buyer's e-mail address | +| `billing_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `note` | `String` | Optional | An optional note to include when creating a payment | + +### Example (as JSON) + +```json +{ + "id": null, + "created_at": null, + "updated_at": null, + "amount_money": null, + "tip_money": null, + "total_money": null, + "app_fee_money": null, + "processing_fee": null, + "refunded_money": null, + "status": null, + "source_type": null, + "card_details": null, + "location_id": null, + "order_id": null, + "reference_id": null, + "customer_id": null, + "employee_id": null, + "refund_ids": null, + "buyer_email_address": null, + "billing_address": null, + "shipping_address": null, + "note": null +} +``` + diff --git a/doc/models/processing-fee.md b/doc/models/processing-fee.md index 97f7d758..0e39acdc 100644 --- a/doc/models/processing-fee.md +++ b/doc/models/processing-fee.md @@ -1,26 +1,26 @@ -## Processing Fee - -Represents Square processing fee. - -### Structure - -`ProcessingFee` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `effective_at` | `String` | Optional | Timestamp of when the fee takes effect, in RFC 3339 format. | -| `type` | `String` | Optional | The type of fee assessed or adjusted. Can be one of: `INITIAL`, `ADJUSTMENT`. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "effective_at": null, - "type": null, - "amount_money": null -} -``` - +## Processing Fee + +Represents Square processing fee. + +### Structure + +`ProcessingFee` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `effective_at` | `String` | Optional | Timestamp of when the fee takes effect, in RFC 3339 format. | +| `type` | `String` | Optional | The type of fee assessed or adjusted. Can be one of: `INITIAL`, `ADJUSTMENT`. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "effective_at": null, + "type": null, + "amount_money": null +} +``` + diff --git a/doc/models/product.md b/doc/models/product.md index cb7c6010..797fc69f 100644 --- a/doc/models/product.md +++ b/doc/models/product.md @@ -1,23 +1,23 @@ -## Product - -Indicates the Square product used to generate an inventory change. - -### Enumeration - -`Product` - -### Fields - -| Name | Description | -| --- | --- | -| `SQUARE_POS` | Square Point of Sale application. | -| `EXTERNAL_API` | Square Connect APIs (Transactions API, Checkout API). | -| `BILLING` | A Square subscription (various products). | -| `APPOINTMENTS` | Square Appointments. | -| `INVOICES` | Square Invoices. | -| `ONLINE_STORE` | Square Online Store. | -| `PAYROLL` | Square Payroll. | -| `DASHBOARD` | Square Dashboard | -| `ITEM_LIBRARY_IMPORT` | Item Library Import | -| `OTHER` | A Square product that does not match any other value. | - +## Product + +Indicates the Square product used to generate an inventory change. + +### Enumeration + +`Product` + +### Fields + +| Name | Description | +| --- | --- | +| `SQUARE_POS` | Square Point of Sale application. | +| `EXTERNAL_API` | Square Connect APIs (Transactions API, Checkout API). | +| `BILLING` | A Square subscription (various products). | +| `APPOINTMENTS` | Square Appointments. | +| `INVOICES` | Square Invoices. | +| `ONLINE_STORE` | Square Online Store. | +| `PAYROLL` | Square Payroll. | +| `DASHBOARD` | Square Dashboard | +| `ITEM_LIBRARY_IMPORT` | Item Library Import | +| `OTHER` | A Square product that does not match any other value. | + diff --git a/doc/models/refund-payment-request.md b/doc/models/refund-payment-request.md index 0810f291..ec0b7848 100644 --- a/doc/models/refund-payment-request.md +++ b/doc/models/refund-payment-request.md @@ -1,31 +1,31 @@ -## Refund Payment Request - -Refunds a payment. - -### Structure - -`RefundPaymentRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `idempotency_key` | `String` | | A unique string that identifies this RefundPayment request. Key can be any valid string but
must be unique for every RefundPayment request.
For more information, see [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency). | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `app_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `payment_id` | `String` | Optional | Unique ID of the payment being refunded. | -| `reason` | `String` | Optional | A description of the reason for the refund. | - -### Example (as JSON) - -```json -{ - "idempotency_key": "a7e36d40-d24b-11e8-b568-0800200c9a66", - "payment_id": "UNOE3kv2BZwqHlJ830RCt5YCuaB", - "amount_money": { - "amount": 100, - "currency": "USD" - } -} -``` - +## Refund Payment Request + +Refunds a payment. + +### Structure + +`RefundPaymentRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `String` | | A unique string that identifies this RefundPayment request. Key can be any valid string but
must be unique for every RefundPayment request.
For more information, see [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency). | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `app_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `payment_id` | `String` | Optional | Unique ID of the payment being refunded. | +| `reason` | `String` | Optional | A description of the reason for the refund. | + +### Example (as JSON) + +```json +{ + "idempotency_key": "a7e36d40-d24b-11e8-b568-0800200c9a66", + "payment_id": "UNOE3kv2BZwqHlJ830RCt5YCuaB", + "amount_money": { + "amount": 100, + "currency": "USD" + } +} +``` + diff --git a/doc/models/refund-payment-response.md b/doc/models/refund-payment-response.md index 3091bbb0..6766012a 100644 --- a/doc/models/refund-payment-response.md +++ b/doc/models/refund-payment-response.md @@ -1,37 +1,37 @@ -## Refund Payment Response - -Defines the fields that are included in the response body of -a request to the [RefundPayment](/doc/refunds.md#refundpayment) endpoint. - -Note: if there are errors processing the request, the refund field may not be -present, or it may be present in a FAILED state. - -### Structure - -`RefundPaymentResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `refund` | [`Payment Refund Hash`](/doc/models/payment-refund.md) | Optional | Represents a refund of a payment made using Square. Contains information on
the original payment and the amount of money refunded. | - -### Example (as JSON) - -```json -{ - "refund": { - "id": "UNOE3kv2BZwqHlJ830RCt5YCuaB_xVteEWVFkXDvKN1ddidfJWipt8p9whmElKT5mZtJ7wZ", - "status": "PENDING", - "amount_money": { - "amount": 100, - "currency": "USD" - }, - "payment_id": "UNOE3kv2BZwqHlJ830RCt5YCuaB", - "created_at": "2018-10-17T20:41:55.520Z", - "updated_at": "2018-10-17T20:41:55.520Z" - } -} -``` - +## Refund Payment Response + +Defines the fields that are included in the response body of +a request to the [RefundPayment](#endpoint-refunds-refundpayment) endpoint. + +Note: if there are errors processing the request, the refund field may not be +present, or it may be present in a FAILED state. + +### Structure + +`RefundPaymentResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `refund` | [`Payment Refund Hash`](/doc/models/payment-refund.md) | Optional | Represents a refund of a payment made using Square. Contains information on
the original payment and the amount of money refunded. | + +### Example (as JSON) + +```json +{ + "refund": { + "id": "UNOE3kv2BZwqHlJ830RCt5YCuaB_xVteEWVFkXDvKN1ddidfJWipt8p9whmElKT5mZtJ7wZ", + "status": "PENDING", + "amount_money": { + "amount": 100, + "currency": "USD" + }, + "payment_id": "UNOE3kv2BZwqHlJ830RCt5YCuaB", + "created_at": "2018-10-17T20:41:55.520Z", + "updated_at": "2018-10-17T20:41:55.520Z" + } +} +``` + diff --git a/doc/models/refund-status.md b/doc/models/refund-status.md index 7414b598..4db152fb 100644 --- a/doc/models/refund-status.md +++ b/doc/models/refund-status.md @@ -1,17 +1,17 @@ -## Refund Status - -Indicates a refund's current status. - -### Enumeration - -`RefundStatus` - -### Fields - -| Name | Description | -| --- | --- | -| `PENDING` | The refund is pending. | -| `APPROVED` | The refund has been approved by Square. | -| `REJECTED` | The refund has been rejected by Square. | -| `FAILED` | The refund failed. | - +## Refund Status + +Indicates a refund's current status. + +### Enumeration + +`RefundStatus` + +### Fields + +| Name | Description | +| --- | --- | +| `PENDING` | The refund is pending. | +| `APPROVED` | The refund has been approved by Square. | +| `REJECTED` | The refund has been rejected by Square. | +| `FAILED` | The refund failed. | + diff --git a/doc/models/refund.md b/doc/models/refund.md index 51e34ad1..9ffe73bc 100644 --- a/doc/models/refund.md +++ b/doc/models/refund.md @@ -1,43 +1,43 @@ -## Refund - -Represents a refund processed for a Square transaction. - -### Structure - -`Refund` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | | The refund's unique ID. | -| `location_id` | `String` | | The ID of the refund's associated location. | -| `transaction_id` | `String` | | The ID of the transaction that the refunded tender is part of. | -| `tender_id` | `String` | | The ID of the refunded tender. | -| `created_at` | `String` | Optional | The time when the refund was created, in RFC 3339 format. | -| `reason` | `String` | | The reason for the refund being issued. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `status` | [`String (Refund Status)`](/doc/models/refund-status.md) | | Indicates a refund's current status. | -| `processing_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `additional_recipients` | [`Array`](/doc/models/additional-recipient.md) | Optional | Additional recipients (other than the merchant) receiving a portion of this refund.
For example, fees assessed on a refund of a purchase by a third party integration. | - -### Example (as JSON) - -```json -{ - "id": "id0", - "location_id": "location_id4", - "transaction_id": "transaction_id8", - "tender_id": "tender_id8", - "created_at": null, - "reason": "reason4", - "amount_money": { - "amount": null, - "currency": null - }, - "status": "PENDING", - "processing_fee_money": null, - "additional_recipients": null -} -``` - +## Refund + +Represents a refund processed for a Square transaction. + +### Structure + +`Refund` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | | The refund's unique ID. | +| `location_id` | `String` | | The ID of the refund's associated location. | +| `transaction_id` | `String` | | The ID of the transaction that the refunded tender is part of. | +| `tender_id` | `String` | | The ID of the refunded tender. | +| `created_at` | `String` | Optional | The time when the refund was created, in RFC 3339 format. | +| `reason` | `String` | | The reason for the refund being issued. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `status` | [`String (Refund Status)`](/doc/models/refund-status.md) | | Indicates a refund's current status. | +| `processing_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `additional_recipients` | [`Array`](/doc/models/additional-recipient.md) | Optional | Additional recipients (other than the merchant) receiving a portion of this refund.
For example, fees assessed on a refund of a purchase by a third party integration. | + +### Example (as JSON) + +```json +{ + "id": "id0", + "location_id": "location_id4", + "transaction_id": "transaction_id8", + "tender_id": "tender_id8", + "created_at": null, + "reason": "reason4", + "amount_money": { + "amount": null, + "currency": null + }, + "status": "PENDING", + "processing_fee_money": null, + "additional_recipients": null +} +``` + diff --git a/doc/models/register-domain-request.md b/doc/models/register-domain-request.md index 4b8805f4..673b87a7 100644 --- a/doc/models/register-domain-request.md +++ b/doc/models/register-domain-request.md @@ -1,23 +1,23 @@ -## Register Domain Request - +## Register Domain Request + Defines the parameters that can be included in the body of -a request to the RegisterDomain endpoint. - -### Structure - -`RegisterDomainRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `domain_name` | `String` | A domain name as described in RFC-1034 that will be registered with ApplePay | - -### Example (as JSON) - -```json -{ - "domain_name": "example.com" -} -``` - +a request to the RegisterDomain endpoint. + +### Structure + +`RegisterDomainRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `domain_name` | `String` | A domain name as described in RFC-1034 that will be registered with ApplePay | + +### Example (as JSON) + +```json +{ + "domain_name": "example.com" +} +``` + diff --git a/doc/models/register-domain-response-status.md b/doc/models/register-domain-response-status.md index 97052401..20944ecc 100644 --- a/doc/models/register-domain-response-status.md +++ b/doc/models/register-domain-response-status.md @@ -1,15 +1,15 @@ -## Register Domain Response Status - -The status of domain registration. - -### Enumeration - -`RegisterDomainResponseStatus` - -### Fields - -| Name | Description | -| --- | --- | -| `PENDING` | The domain is added, but not verified. | -| `VERIFIED` | The domain is added and verified. It can be used to accept Apple Pay transactions. | - +## Register Domain Response Status + +The status of domain registration. + +### Enumeration + +`RegisterDomainResponseStatus` + +### Fields + +| Name | Description | +| --- | --- | +| `PENDING` | The domain is added, but not verified. | +| `VERIFIED` | The domain is added and verified. It can be used to accept Apple Pay transactions. | + diff --git a/doc/models/register-domain-response.md b/doc/models/register-domain-response.md index a6f084df..d99ddf1d 100644 --- a/doc/models/register-domain-response.md +++ b/doc/models/register-domain-response.md @@ -1,26 +1,26 @@ -## Register Domain Response - -Defines the fields that are included in the response body of -a request to the RegisterDomain endpoint. - -Either `errors` or `status` will be present in a given response (never both). - -### Structure - -`RegisterDomainResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `status` | [`String (Register Domain Response Status)`](/doc/models/register-domain-response-status.md) | Optional | The status of domain registration. | - -### Example (as JSON) - -```json -{ - "status": "VERIFIED" -} -``` - +## Register Domain Response + +Defines the fields that are included in the response body of +a request to the RegisterDomain endpoint. + +Either `errors` or `status` will be present in a given response (never both). + +### Structure + +`RegisterDomainResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `status` | [`String (Register Domain Response Status)`](/doc/models/register-domain-response-status.md) | Optional | The status of domain registration. | + +### Example (as JSON) + +```json +{ + "status": "VERIFIED" +} +``` + diff --git a/doc/models/renew-token-request.md b/doc/models/renew-token-request.md index d487132b..9e673a35 100644 --- a/doc/models/renew-token-request.md +++ b/doc/models/renew-token-request.md @@ -1,20 +1,20 @@ -## Renew Token Request - -### Structure - -`RenewTokenRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `access_token` | `String` | Optional | The token you want to renew. | - -### Example (as JSON) - -```json -{ - "access_token": "ACCESS_TOKEN" -} -``` - +## Renew Token Request + +### Structure + +`RenewTokenRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `access_token` | `String` | Optional | The token you want to renew. | + +### Example (as JSON) + +```json +{ + "access_token": "ACCESS_TOKEN" +} +``` + diff --git a/doc/models/renew-token-response.md b/doc/models/renew-token-response.md index 3d349e22..286ca7b4 100644 --- a/doc/models/renew-token-response.md +++ b/doc/models/renew-token-response.md @@ -1,28 +1,28 @@ -## Renew Token Response - -### Structure - -`RenewTokenResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `access_token` | `String` | Optional | The renewed access token.
This value might be different from the `access_token` you provided in your request.
You provide this token in a header with every request to Connect API endpoints.
See [Request and response headers](https://docs.connect.squareup.com/api/connect/v2/#requestandresponseheaders) for the format of this header. | -| `token_type` | `String` | Optional | This value is always _bearer_. | -| `expires_at` | `String` | Optional | The date when access_token expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format. | -| `merchant_id` | `String` | Optional | The ID of the authorizing merchant's business. | -| `subscription_id` | `String` | Optional | __LEGACY FIELD__. The ID of the merchant subscription associated with
the authorization. Only present if the merchant signed up for a subscription
during authorization. | -| `plan_id` | `String` | Optional | __LEGACY FIELD__. The ID of the subscription plan the merchant signed
up for. Only present if the merchant signed up for a subscription during
authorization. | - -### Example (as JSON) - -```json -{ - "access_token": "ACCESS_TOKEN", - "token_type": "bearer", - "expires_at": "2006-01-02T15:04:05Z", - "merchant_id": "MERCHANT_ID" -} -``` - +## Renew Token Response + +### Structure + +`RenewTokenResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `access_token` | `String` | Optional | The renewed access token.
This value might be different from the `access_token` you provided in your request.
You provide this token in a header with every request to Connect API endpoints.
See [Request and response headers](https://docs.connect.squareup.com/api/connect/v2/#requestandresponseheaders) for the format of this header. | +| `token_type` | `String` | Optional | This value is always _bearer_. | +| `expires_at` | `String` | Optional | The date when access_token expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format. | +| `merchant_id` | `String` | Optional | The ID of the authorizing merchant's business. | +| `subscription_id` | `String` | Optional | __LEGACY FIELD__. The ID of the merchant subscription associated with
the authorization. Only present if the merchant signed up for a subscription
during authorization. | +| `plan_id` | `String` | Optional | __LEGACY FIELD__. The ID of the subscription plan the merchant signed
up for. Only present if the merchant signed up for a subscription during
authorization. | + +### Example (as JSON) + +```json +{ + "access_token": "ACCESS_TOKEN", + "token_type": "bearer", + "expires_at": "2006-01-02T15:04:05Z", + "merchant_id": "MERCHANT_ID" +} +``` + diff --git a/doc/models/retrieve-catalog-object-request.md b/doc/models/retrieve-catalog-object-request.md index 33db87fc..61665cce 100644 --- a/doc/models/retrieve-catalog-object-request.md +++ b/doc/models/retrieve-catalog-object-request.md @@ -1,20 +1,20 @@ -## Retrieve Catalog Object Request - -### Structure - -`RetrieveCatalogObjectRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `include_related_objects` | `Boolean` | Optional | If `true`, the response will include additional objects that are related to the
requested object, as follows:

If the `object` field of the response contains a [CatalogItem](./models/catalog-item.md),
its associated [CatalogCategory](./models/catalog-category.md), [CatalogTax](./models/catalog-tax.md)es,
[CatalogImage](./models/catalog-image.md)s and [CatalogModifierList](./models/catalog-modifier-list.md)s
will be returned in the `related_objects` field of the response. If the `object`
field of the response contains a [CatalogItemVariation](./models/catalog-item-variation.md),
its parent [CatalogItem](./models/catalog-item.md) will be returned in the `related_objects` field of
the response.

Default value: `false` | - -### Example (as JSON) - -```json -{ - "include_related_objects": null -} -``` - +## Retrieve Catalog Object Request + +### Structure + +`RetrieveCatalogObjectRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `include_related_objects` | `Boolean` | Optional | If `true`, the response will include additional objects that are related to the
requested object, as follows:

If the `object` field of the response contains a [CatalogItem](#type-catalogitem),
its associated [CatalogCategory](#type-catalogcategory), [CatalogTax](#type-catalogtax)es,
[CatalogImage](#type-catalogimage)s and [CatalogModifierList](#type-catalogmodifierlist)s
will be returned in the `related_objects` field of the response. If the `object`
field of the response contains a [CatalogItemVariation](#type-catalogitemvariation),
its parent [CatalogItem](#type-catalogitem) will be returned in the `related_objects` field of
the response.

Default value: `false` | + +### Example (as JSON) + +```json +{ + "include_related_objects": null +} +``` + diff --git a/doc/models/retrieve-catalog-object-response.md b/doc/models/retrieve-catalog-object-response.md index db938d35..2121f662 100644 --- a/doc/models/retrieve-catalog-object-response.md +++ b/doc/models/retrieve-catalog-object-response.md @@ -1,85 +1,85 @@ -## Retrieve Catalog Object Response - -### Structure - -`RetrieveCatalogObjectResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `object` | [`Catalog Object Hash`](/doc/models/catalog-object.md) | Optional | - | -| `related_objects` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](./models/catalog-object.md)s referenced by the object in the `object` field. | - -### Example (as JSON) - -```json -{ - "object": { - "type": "ITEM", - "id": "W62UWFY35CWMYGVWK6TWJDNI", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "item_data": { - "name": "Tea", - "description": "Hot Leaf Juice", - "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX", - "tax_ids": [ - "HURXQOOAIC4IZSI2BEXQRYFY" - ], - "variations": [ - { - "type": "ITEM_VARIATION", - "id": "2TZFAOHWGG7PAK2QEXWYPZSP", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "W62UWFY35CWMYGVWK6TWJDNI", - "name": "Mug", - "ordinal": 0, - "pricing_type": "FIXED_PRICING", - "price_money": { - "amount": 150, - "currency": "USD" - } - } - } - ] - } - }, - "related_objects": [ - { - "type": "CATEGORY", - "id": "BJNQCF2FJ6S6UIDT65ABHLRX", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "category_data": { - "name": "Beverages" - } - }, - { - "type": "TAX", - "id": "HURXQOOAIC4IZSI2BEXQRYFY", - "updated_at": "2016-11-16T22:25:24.878Z", - "version": 1479335124878, - "is_deleted": false, - "present_at_all_locations": true, - "tax_data": { - "name": "Sales Tax", - "calculation_phase": "TAX_SUBTOTAL_PHASE", - "inclusion_type": "ADDITIVE", - "percentage": "5.0", - "enabled": true - } - } - ] -} -``` - +## Retrieve Catalog Object Response + +### Structure + +`RetrieveCatalogObjectResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `object` | [`Catalog Object Hash`](/doc/models/catalog-object.md) | Optional | - | +| `related_objects` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](#type-catalogobject)s referenced by the object in the `object` field. | + +### Example (as JSON) + +```json +{ + "object": { + "type": "ITEM", + "id": "W62UWFY35CWMYGVWK6TWJDNI", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "item_data": { + "name": "Tea", + "description": "Hot Leaf Juice", + "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX", + "tax_ids": [ + "HURXQOOAIC4IZSI2BEXQRYFY" + ], + "variations": [ + { + "type": "ITEM_VARIATION", + "id": "2TZFAOHWGG7PAK2QEXWYPZSP", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "W62UWFY35CWMYGVWK6TWJDNI", + "name": "Mug", + "ordinal": 0, + "pricing_type": "FIXED_PRICING", + "price_money": { + "amount": 150, + "currency": "USD" + } + } + } + ] + } + }, + "related_objects": [ + { + "type": "CATEGORY", + "id": "BJNQCF2FJ6S6UIDT65ABHLRX", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "category_data": { + "name": "Beverages" + } + }, + { + "type": "TAX", + "id": "HURXQOOAIC4IZSI2BEXQRYFY", + "updated_at": "2016-11-16T22:25:24.878Z", + "version": 1479335124878, + "is_deleted": false, + "present_at_all_locations": true, + "tax_data": { + "name": "Sales Tax", + "calculation_phase": "TAX_SUBTOTAL_PHASE", + "inclusion_type": "ADDITIVE", + "percentage": "5.0", + "enabled": true + } + } + ] +} +``` + diff --git a/doc/models/retrieve-customer-response.md b/doc/models/retrieve-customer-response.md index e9e7537b..cfcdbf87 100644 --- a/doc/models/retrieve-customer-response.md +++ b/doc/models/retrieve-customer-response.md @@ -1,50 +1,50 @@ -## Retrieve Customer Response - -Defines the fields that are included in the response body of -a request to the RetrieveCustomer endpoint. - -One of `errors` or `customer` is present in a given response (never both). - -### Structure - -`RetrieveCustomerResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `customer` | [`Customer Hash`](/doc/models/customer.md) | Optional | Represents one of a business's customers, which can have one or more
cards on file associated with it. | - -### Example (as JSON) - -```json -{ - "customer": { - "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", - "created_at": "2016-03-23T20:21:54.859Z", - "updated_at": "2016-03-23T20:21:54.859Z", - "given_name": "Amelia", - "family_name": "Earhart", - "email_address": "Amelia.Earhart@example.com", - "address": { - "address_line_1": "500 Electric Ave", - "address_line_2": "Suite 600", - "locality": "New York", - "administrative_district_level_1": "NY", - "postal_code": "10003", - "country": "US" - }, - "phone_number": "1-212-555-4240", - "reference_id": "YOUR_REFERENCE_ID", - "note": "a customer", - "groups": [ - { - "id": "16894e93-96eb-4ced-b24b-f71d42bf084c", - "name": "Aviation Enthusiasts" - } - ] - } -} -``` - +## Retrieve Customer Response + +Defines the fields that are included in the response body of +a request to the RetrieveCustomer endpoint. + +One of `errors` or `customer` is present in a given response (never both). + +### Structure + +`RetrieveCustomerResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `customer` | [`Customer Hash`](/doc/models/customer.md) | Optional | Represents one of a business's customers, which can have one or more
cards on file associated with it. | + +### Example (as JSON) + +```json +{ + "customer": { + "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", + "created_at": "2016-03-23T20:21:54.859Z", + "updated_at": "2016-03-23T20:21:54.859Z", + "given_name": "Amelia", + "family_name": "Earhart", + "email_address": "Amelia.Earhart@example.com", + "address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "locality": "New York", + "administrative_district_level_1": "NY", + "postal_code": "10003", + "country": "US" + }, + "phone_number": "1-212-555-4240", + "reference_id": "YOUR_REFERENCE_ID", + "note": "a customer", + "groups": [ + { + "id": "16894e93-96eb-4ced-b24b-f71d42bf084c", + "name": "Aviation Enthusiasts" + } + ] + } +} +``` + diff --git a/doc/models/retrieve-employee-response.md b/doc/models/retrieve-employee-response.md index d1f7539d..9e30ba59 100644 --- a/doc/models/retrieve-employee-response.md +++ b/doc/models/retrieve-employee-response.md @@ -1,27 +1,27 @@ -## Retrieve Employee Response - -Defines the fields that are included in the response body of -a request to the RetrieveEmployee endpoint. - -One of `errors` or `employee` is present in a given response (never both). - -### Structure - -`RetrieveEmployeeResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `employee` | [`Employee Hash`](/doc/models/employee.md) | Optional | An employee created in the **Square Dashboard** account of a business.
Used by the Labor API. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "employee": null, - "errors": null -} -``` - +## Retrieve Employee Response + +Defines the fields that are included in the response body of +a request to the RetrieveEmployee endpoint. + +One of `errors` or `employee` is present in a given response (never both). + +### Structure + +`RetrieveEmployeeResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `employee` | [`Employee Hash`](/doc/models/employee.md) | Optional | An employee created in the **Square Dashboard** account of a business.
Used by the Labor API. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "employee": null, + "errors": null +} +``` + diff --git a/doc/models/retrieve-inventory-adjustment-response.md b/doc/models/retrieve-inventory-adjustment-response.md index d64e1768..7765e3a2 100644 --- a/doc/models/retrieve-inventory-adjustment-response.md +++ b/doc/models/retrieve-inventory-adjustment-response.md @@ -1,43 +1,43 @@ -## Retrieve Inventory Adjustment Response - -### Structure - -`RetrieveInventoryAdjustmentResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `adjustment` | [`Inventory Adjustment Hash`](/doc/models/inventory-adjustment.md) | Optional | Represents a change in state or quantity of product inventory at a
particular time and location. | - -### Example (as JSON) - -```json -{ - "errors": [], - "adjustment": { - "id": "UDMOEO78BG6GYWA2XDRYX3KB", - "reference_id": "4a366069-4096-47a2-99a5-0084ac879509", - "from_state": "IN_STOCK", - "to_state": "SOLD", - "location_id": "C6W5YS5QM06F5", - "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", - "catalog_object_type": "ITEM_VARIATION", - "quantity": "7", - "total_price_money": { - "amount": 4550, - "currency": "USD" - }, - "occurred_at": "2016-11-16T25:44:22.837Z", - "created_at": "2016-11-17T13:02:15.142Z", - "source": { - "product": "SQUARE_POS", - "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0", - "name": "Square Point of Sale 4.37" - }, - "employee_id": "LRK57NSQ5X7PUD05" - } -} -``` - +## Retrieve Inventory Adjustment Response + +### Structure + +`RetrieveInventoryAdjustmentResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `adjustment` | [`Inventory Adjustment Hash`](/doc/models/inventory-adjustment.md) | Optional | Represents a change in state or quantity of product inventory at a
particular time and location. | + +### Example (as JSON) + +```json +{ + "errors": [], + "adjustment": { + "id": "UDMOEO78BG6GYWA2XDRYX3KB", + "reference_id": "4a366069-4096-47a2-99a5-0084ac879509", + "from_state": "IN_STOCK", + "to_state": "SOLD", + "location_id": "C6W5YS5QM06F5", + "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", + "catalog_object_type": "ITEM_VARIATION", + "quantity": "7", + "total_price_money": { + "amount": 4550, + "currency": "USD" + }, + "occurred_at": "2016-11-16T25:44:22.837Z", + "created_at": "2016-11-17T13:02:15.142Z", + "source": { + "product": "SQUARE_POS", + "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0", + "name": "Square Point of Sale 4.37" + }, + "employee_id": "LRK57NSQ5X7PUD05" + } +} +``` + diff --git a/doc/models/retrieve-inventory-changes-request.md b/doc/models/retrieve-inventory-changes-request.md index 6907cd72..9e81ff1c 100644 --- a/doc/models/retrieve-inventory-changes-request.md +++ b/doc/models/retrieve-inventory-changes-request.md @@ -1,22 +1,22 @@ -## Retrieve Inventory Changes Request - -### Structure - -`RetrieveInventoryChangesRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_ids` | `String` | Optional | The [Location](./models/location.md) IDs to look up as a comma-separated
list. An empty list queries all locations. | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "location_ids": null, - "cursor": null -} -``` - +## Retrieve Inventory Changes Request + +### Structure + +`RetrieveInventoryChangesRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_ids` | `String` | Optional | The [Location](#type-location) IDs to look up as a comma-separated
list. An empty list queries all locations. | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "location_ids": null, + "cursor": null +} +``` + diff --git a/doc/models/retrieve-inventory-changes-response.md b/doc/models/retrieve-inventory-changes-response.md index f634d0ea..4b5bec9f 100644 --- a/doc/models/retrieve-inventory-changes-response.md +++ b/doc/models/retrieve-inventory-changes-response.md @@ -1,50 +1,50 @@ -## Retrieve Inventory Changes Response - -### Structure - -`RetrieveInventoryChangesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `changes` | [`Array`](/doc/models/inventory-change.md) | Optional | The set of inventory changes for the requested object and locations. | -| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "errors": [], - "changes": [ - { - "type": "ADJUSTMENT", - "adjustment": { - "id": "OJKJIUANKLMLQANZADNPLKAD", - "reference_id": "d8207693-168f-4b44-a2fd-a7ff533ddd26", - "from_state": "IN_STOCK", - "to_state": "SOLD", - "location_id": "C6W5YS5QM06F5", - "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", - "catalog_object_type": "ITEM_VARIATION", - "quantity": "3", - "total_price_money": { - "amount": 5000, - "currency": "USD" - }, - "occurred_at": "2016-11-16T22:25:24.878Z", - "created_at": "2016-11-16T22:25:24.878Z", - "source": { - "product": "SQUARE_POS", - "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0", - "name": "Square Point of Sale 4.37" - }, - "employee_id": "AV7YRCGI2H1J5NQ8E1XIZCNA", - "transaction_id": "5APV6JYK1SNCZD11AND2RX1Z" - } - } - ] -} -``` - +## Retrieve Inventory Changes Response + +### Structure + +`RetrieveInventoryChangesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `changes` | [`Array`](/doc/models/inventory-change.md) | Optional | The set of inventory changes for the requested object and locations. | +| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "errors": [], + "changes": [ + { + "type": "ADJUSTMENT", + "adjustment": { + "id": "OJKJIUANKLMLQANZADNPLKAD", + "reference_id": "d8207693-168f-4b44-a2fd-a7ff533ddd26", + "from_state": "IN_STOCK", + "to_state": "SOLD", + "location_id": "C6W5YS5QM06F5", + "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", + "catalog_object_type": "ITEM_VARIATION", + "quantity": "3", + "total_price_money": { + "amount": 5000, + "currency": "USD" + }, + "occurred_at": "2016-11-16T22:25:24.878Z", + "created_at": "2016-11-16T22:25:24.878Z", + "source": { + "product": "SQUARE_POS", + "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0", + "name": "Square Point of Sale 4.37" + }, + "employee_id": "AV7YRCGI2H1J5NQ8E1XIZCNA", + "transaction_id": "5APV6JYK1SNCZD11AND2RX1Z" + } + } + ] +} +``` + diff --git a/doc/models/retrieve-inventory-count-request.md b/doc/models/retrieve-inventory-count-request.md index 1f5186d2..38c3a9bb 100644 --- a/doc/models/retrieve-inventory-count-request.md +++ b/doc/models/retrieve-inventory-count-request.md @@ -1,22 +1,22 @@ -## Retrieve Inventory Count Request - -### Structure - -`RetrieveInventoryCountRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_ids` | `String` | Optional | The [Location](./models/location.md) IDs to look up as a comma-separated
list. An empty list queries all locations. | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "location_ids": null, - "cursor": null -} -``` - +## Retrieve Inventory Count Request + +### Structure + +`RetrieveInventoryCountRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_ids` | `String` | Optional | The [Location](#type-location) IDs to look up as a comma-separated
list. An empty list queries all locations. | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "location_ids": null, + "cursor": null +} +``` + diff --git a/doc/models/retrieve-inventory-count-response.md b/doc/models/retrieve-inventory-count-response.md index a351925f..0d35adde 100644 --- a/doc/models/retrieve-inventory-count-response.md +++ b/doc/models/retrieve-inventory-count-response.md @@ -1,32 +1,32 @@ -## Retrieve Inventory Count Response - -### Structure - -`RetrieveInventoryCountResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `counts` | [`Array`](/doc/models/inventory-count.md) | Optional | The current calculated inventory counts for the requested object and
locations. | -| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "errors": [], - "counts": [ - { - "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", - "catalog_object_type": "ITEM_VARIATION", - "state": "IN_STOCK", - "location_id": "C6W5YS5QM06F5", - "quantity": "22", - "calculated_at": "2016-11-16T22:28:01.223Z" - } - ] -} -``` - +## Retrieve Inventory Count Response + +### Structure + +`RetrieveInventoryCountResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `counts` | [`Array`](/doc/models/inventory-count.md) | Optional | The current calculated inventory counts for the requested object and
locations. | +| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "errors": [], + "counts": [ + { + "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", + "catalog_object_type": "ITEM_VARIATION", + "state": "IN_STOCK", + "location_id": "C6W5YS5QM06F5", + "quantity": "22", + "calculated_at": "2016-11-16T22:28:01.223Z" + } + ] +} +``` + diff --git a/doc/models/retrieve-inventory-physical-count-response.md b/doc/models/retrieve-inventory-physical-count-response.md index 2847033a..7198c226 100644 --- a/doc/models/retrieve-inventory-physical-count-response.md +++ b/doc/models/retrieve-inventory-physical-count-response.md @@ -1,38 +1,38 @@ -## Retrieve Inventory Physical Count Response - -### Structure - -`RetrieveInventoryPhysicalCountResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `count` | [`Inventory Physical Count Hash`](/doc/models/inventory-physical-count.md) | Optional | Represents the quantity of an item variation that is physically present
at a specific location, verified by a seller or a seller's employee. For example,
a physical count might come from an employee counting the item variations on
hand or from syncing with an external system. | - -### Example (as JSON) - -```json -{ - "errors": [], - "count": { - "id": "ANZADNPLKADOJKJIUANKLMLQ", - "reference_id": "f857ec37-f9a0-4458-8e23-5b5e0bea4e53", - "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", - "catalog_object_type": "ITEM_VARIATION", - "state": "IN_STOCK", - "location_id": "C6W5YS5QM06F5", - "quantity": "15", - "source": { - "product": "SQUARE_POS", - "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0", - "name": "Square Point of Sale 4.37" - }, - "employee_id": "LRK57NSQ5X7PUD05", - "occurred_at": "2016-11-16T22:25:24.878Z", - "created_at": "2016-11-16T22:25:24.878Z" - } -} -``` - +## Retrieve Inventory Physical Count Response + +### Structure + +`RetrieveInventoryPhysicalCountResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `count` | [`Inventory Physical Count Hash`](/doc/models/inventory-physical-count.md) | Optional | Represents the quantity of an item variation that is physically present
at a specific location, verified by a seller or a seller's employee. For example,
a physical count might come from an employee counting the item variations on
hand or from syncing with an external system. | + +### Example (as JSON) + +```json +{ + "errors": [], + "count": { + "id": "ANZADNPLKADOJKJIUANKLMLQ", + "reference_id": "f857ec37-f9a0-4458-8e23-5b5e0bea4e53", + "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", + "catalog_object_type": "ITEM_VARIATION", + "state": "IN_STOCK", + "location_id": "C6W5YS5QM06F5", + "quantity": "15", + "source": { + "product": "SQUARE_POS", + "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0", + "name": "Square Point of Sale 4.37" + }, + "employee_id": "LRK57NSQ5X7PUD05", + "occurred_at": "2016-11-16T22:25:24.878Z", + "created_at": "2016-11-16T22:25:24.878Z" + } +} +``` + diff --git a/doc/models/retrieve-location-response.md b/doc/models/retrieve-location-response.md new file mode 100644 index 00000000..f0e56d17 --- /dev/null +++ b/doc/models/retrieve-location-response.md @@ -0,0 +1,47 @@ +## Retrieve Location Response + +Defines the fields that the +[RetrieveLocation](#endpoint-retrievelocation) endpoint returns +in a response. + +### Structure + +`RetrieveLocationResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `location` | [`Location Hash`](/doc/models/location.md) | Optional | Represents one of a business's locations. | + +### Example (as JSON) + +```json +{ + "location": { + "id": "18YC4JDH91E1H", + "name": "Jet Fuel Coffee - Grant Park", + "address": { + "address_line_1": "123 Main St", + "locality": "San Francisco", + "administrative_district_level_1": "CA", + "postal_code": "94114", + "country": "US" + }, + "timezone": "America/Los_Angeles", + "capabilities": [ + "CREDIT_CARD_PROCESSING" + ], + "status": "ACTIVE", + "created_at": "2016-09-19T17:33:12Z", + "merchant_id": "3MYCJG5GVYQ8Q", + "country": "US", + "language_code": "en-US", + "currency": "USD", + "phone_number": "+1 650-354-7217", + "business_name": "Jet Fuel Coffee" + } +} +``` + diff --git a/doc/models/retrieve-merchant-response.md b/doc/models/retrieve-merchant-response.md new file mode 100644 index 00000000..664608c4 --- /dev/null +++ b/doc/models/retrieve-merchant-response.md @@ -0,0 +1,30 @@ +## Retrieve Merchant Response + +The response obeject returned by the [RetrieveMerchant](#endpoint-retrieveMerchant) endpoint. + +### Structure + +`RetrieveMerchantResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `merchant` | [`Merchant Hash`](/doc/models/merchant.md) | Optional | Represents a Square seller. | + +### Example (as JSON) + +```json +{ + "merchant": { + "id": "DM7VKY8Q63GNP", + "business_name": "Apple A Day", + "country": "US", + "language_code": "en-US", + "currency": "USD", + "status": "ACTIVE" + } +} +``` + diff --git a/doc/models/retrieve-transaction-response.md b/doc/models/retrieve-transaction-response.md index e05bdf64..aa53e0bc 100644 --- a/doc/models/retrieve-transaction-response.md +++ b/doc/models/retrieve-transaction-response.md @@ -1,68 +1,68 @@ -## Retrieve Transaction Response - -Defines the fields that are included in the response body of -a request to the [RetrieveTransaction](#endpont-retrievetransaction) endpoint. - -One of `errors` or `transaction` is present in a given response (never both). - -### Structure - -`RetrieveTransactionResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `transaction` | [`Transaction Hash`](/doc/models/transaction.md) | Optional | Represents a transaction processed with Square, either with the
Connect API or with Square Point of Sale.

The `tenders` field of this object lists all methods of payment used to pay in
the transaction. | - -### Example (as JSON) - -```json -{ - "transaction": { - "id": "KnL67ZIwXCPtzOrqj0HrkxMF", - "location_id": "18YC4JDH91E1H", - "created_at": "2016-03-10T22:57:56Z", - "tenders": [ - { - "id": "MtZRYYdDrYNQbOvV7nbuBvMF", - "location_id": "18YC4JDH91E1H", - "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", - "created_at": "2016-03-10T22:57:56Z", - "note": "some optional note", - "amount_money": { - "amount": 5000, - "currency": "USD" - }, - "processing_fee_money": { - "amount": 138, - "currency": "USD" - }, - "type": "CARD", - "card_details": { - "status": "CAPTURED", - "card": { - "card_brand": "VISA", - "last_4": "1111" - }, - "entry_method": "KEYED" - }, - "additional_recipients": [ - { - "location_id": "057P5VYJ4A5X1", - "description": "Application fees", - "amount_money": { - "amount": 20, - "currency": "USD" - } - } - ] - } - ], - "reference_id": "some optional reference id", - "product": "EXTERNAL_API" - } -} -``` - +## Retrieve Transaction Response + +Defines the fields that are included in the response body of +a request to the [RetrieveTransaction](#endpont-retrievetransaction) endpoint. + +One of `errors` or `transaction` is present in a given response (never both). + +### Structure + +`RetrieveTransactionResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `transaction` | [`Transaction Hash`](/doc/models/transaction.md) | Optional | Represents a transaction processed with Square, either with the
Connect API or with Square Point of Sale.

The `tenders` field of this object lists all methods of payment used to pay in
the transaction. | + +### Example (as JSON) + +```json +{ + "transaction": { + "id": "KnL67ZIwXCPtzOrqj0HrkxMF", + "location_id": "18YC4JDH91E1H", + "created_at": "2016-03-10T22:57:56Z", + "tenders": [ + { + "id": "MtZRYYdDrYNQbOvV7nbuBvMF", + "location_id": "18YC4JDH91E1H", + "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF", + "created_at": "2016-03-10T22:57:56Z", + "note": "some optional note", + "amount_money": { + "amount": 5000, + "currency": "USD" + }, + "processing_fee_money": { + "amount": 138, + "currency": "USD" + }, + "type": "CARD", + "card_details": { + "status": "CAPTURED", + "card": { + "card_brand": "VISA", + "last_4": "1111" + }, + "entry_method": "KEYED" + }, + "additional_recipients": [ + { + "location_id": "057P5VYJ4A5X1", + "description": "Application fees", + "amount_money": { + "amount": 20, + "currency": "USD" + } + } + ] + } + ], + "reference_id": "some optional reference id", + "product": "EXTERNAL_API" + } +} +``` + diff --git a/doc/models/revoke-token-request.md b/doc/models/revoke-token-request.md index 4cd3996d..8b31dd78 100644 --- a/doc/models/revoke-token-request.md +++ b/doc/models/revoke-token-request.md @@ -1,23 +1,23 @@ -## Revoke Token Request - -### Structure - -`RevokeTokenRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `client_id` | `String` | Optional | Your application's ID, available from the [application dashboard](https://connect.squareup.com/apps). | -| `access_token` | `String` | Optional | The access token of the merchant whose token you want to revoke.
Do not provide a value for merchant_id if you provide this parameter. | -| `merchant_id` | `String` | Optional | The ID of the merchant whose token you want to revoke.
Do not provide a value for access_token if you provide this parameter. | - -### Example (as JSON) - -```json -{ - "access_token": "ACCESS_TOKEN", - "client_id": "CLIENT_ID" -} -``` - +## Revoke Token Request + +### Structure + +`RevokeTokenRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `client_id` | `String` | Optional | Your application's ID, available from the [application dashboard](https://connect.squareup.com/apps). | +| `access_token` | `String` | Optional | The access token of the merchant whose token you want to revoke.
Do not provide a value for merchant_id if you provide this parameter. | +| `merchant_id` | `String` | Optional | The ID of the merchant whose token you want to revoke.
Do not provide a value for access_token if you provide this parameter. | + +### Example (as JSON) + +```json +{ + "access_token": "ACCESS_TOKEN", + "client_id": "CLIENT_ID" +} +``` + diff --git a/doc/models/revoke-token-response.md b/doc/models/revoke-token-response.md index 3914b819..d62ec93a 100644 --- a/doc/models/revoke-token-response.md +++ b/doc/models/revoke-token-response.md @@ -1,20 +1,20 @@ -## Revoke Token Response - -### Structure - -`RevokeTokenResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `success` | `Boolean` | Optional | If the request is successful, this is true. | - -### Example (as JSON) - -```json -{ - "success": true -} -``` - +## Revoke Token Response + +### Structure + +`RevokeTokenResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `success` | `Boolean` | Optional | If the request is successful, this is true. | + +### Example (as JSON) + +```json +{ + "success": true +} +``` + diff --git a/doc/models/search-catalog-objects-request.md b/doc/models/search-catalog-objects-request.md index 86ce00d7..b8a45ba6 100644 --- a/doc/models/search-catalog-objects-request.md +++ b/doc/models/search-catalog-objects-request.md @@ -1,35 +1,35 @@ -## Search Catalog Objects Request - -### Structure - -`SearchCatalogObjectsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `cursor` | `String` | Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `object_types` | [`Array`](/doc/models/catalog-object-type.md) | Optional | The desired set of object types to appear in the search results. The legal values are taken from the
[CatalogObjectType](./models/catalog-object-type.md) enumeration, namely `"ITEM"`, `"ITEM_VARIATION"`, `"CATEGORY"`,
`"DISCOUNT"`, `"TAX"`, `"MODIFIER"`, or `"MODIFIER_LIST"`.
See [CatalogObjectType](./models/catalog-object-type.md) for possible values | -| `include_deleted_objects` | `Boolean` | Optional | If `true`, deleted objects will be included in the results. Deleted objects will have their
`is_deleted` field set to `true`. | -| `include_related_objects` | `Boolean` | Optional | If `true`, the response will include additional objects that are related to the
requested object, as follows:

If a [CatalogItem](./models/catalog-item.md) is returned in the object field of the response,
its associated [CatalogCategory](./models/catalog-category.md), [CatalogTax](./models/catalog-tax.md)es,
[CatalogImage](./models/catalog-image.md)s and [CatalogModifierList](./models/catalog-modifier-list.md)s
will be included in the `related_objects` field of the response.

If a [CatalogItemVariation](./models/catalog-item-variation.md) is returned in the object field of the
response, its parent [CatalogItem](./models/catalog-item.md) will be included in the `related_objects` field of
the response. | -| `begin_time` | `String` | Optional | Return objects modified after this [timestamp](#workingwithdates), in RFC 3339
format, e.g., "2016-09-04T23:59:33.123Z". The timestamp is exclusive - objects with a
timestamp equal to `begin_time` will not be included in the response. | -| `query` | [`Catalog Query Hash`](/doc/models/catalog-query.md) | Optional | A query to be applied to a [SearchCatalogObjectsRequest](./models/search-catalog-objects-request.md).
Only one query field may be present.

Where an attribute name is required, it should be specified as the name of any field
marked "searchable" from the structured data types for the desired result object type(s)
([CatalogItem](./models/catalog-item.md), [CatalogItemVariation](./models/catalog-item-variation.md),
[CatalogCategory](./models/catalog-category.md), [CatalogTax](./models/catalog-tax.md),
[CatalogDiscount](./models/catalog-discount.md), [CatalogModifierList](./models/catalog-modifier-list.md),
[CatalogModifier](./models/catalog-modifier.md)).

For example, a query that should return Items may specify attribute names from
any of the searchable fields of the [CatalogItem](./models/catalog-item.md) data type, namely
`"name"`, `"description"`, and `"abbreviation"`. | -| `limit` | `Integer` | Optional | A limit on the number of results to be returned in a single page. The limit is advisory -
the implementation may return more or fewer results. If the supplied limit is negative, zero, or
is higher than the maximum limit of 1,000, it will be ignored. | - -### Example (as JSON) - -```json -{ - "object_types": [ - "ITEM" - ], - "query": { - "prefix_query": { - "attribute_name": "name", - "attribute_prefix": "tea" - } - }, - "limit": 100 -} -``` - +## Search Catalog Objects Request + +### Structure + +`SearchCatalogObjectsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `cursor` | `String` | Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `object_types` | [`Array`](/doc/models/catalog-object-type.md) | Optional | The desired set of object types to appear in the search results. The legal values are taken from the
[CatalogObjectType](#type-catalogobjecttype) enumeration, namely `"ITEM"`, `"ITEM_VARIATION"`, `"CATEGORY"`,
`"DISCOUNT"`, `"TAX"`, `"MODIFIER"`, or `"MODIFIER_LIST"`.
See [CatalogObjectType](#type-catalogobjecttype) for possible values | +| `include_deleted_objects` | `Boolean` | Optional | If `true`, deleted objects will be included in the results. Deleted objects will have their
`is_deleted` field set to `true`. | +| `include_related_objects` | `Boolean` | Optional | If `true`, the response will include additional objects that are related to the
requested object, as follows:

If a [CatalogItem](#type-catalogitem) is returned in the object field of the response,
its associated [CatalogCategory](#type-catalogcategory), [CatalogTax](#type-catalogtax)es,
[CatalogImage](#type-catalogimage)s and [CatalogModifierList](#type-catalogmodifierlist)s
will be included in the `related_objects` field of the response.

If a [CatalogItemVariation](#type-catalogitemvariation) is returned in the object field of the
response, its parent [CatalogItem](#type-catalogitem) will be included in the `related_objects` field of
the response. | +| `begin_time` | `String` | Optional | Return objects modified after this [timestamp](#workingwithdates), in RFC 3339
format, e.g., "2016-09-04T23:59:33.123Z". The timestamp is exclusive - objects with a
timestamp equal to `begin_time` will not be included in the response. | +| `query` | [`Catalog Query Hash`](/doc/models/catalog-query.md) | Optional | A query to be applied to a [SearchCatalogObjectsRequest](#type-searchcatalogobjectsrequest).
Only one query field may be present.

Where an attribute name is required, it should be specified as the name of any field
marked "searchable" from the structured data types for the desired result object type(s)
([CatalogItem](#type-catalogitem), [CatalogItemVariation](#type-catalogitemvariation),
[CatalogCategory](#type-catalogcategory), [CatalogTax](#type-catalogtax),
[CatalogDiscount](#type-catalogdiscount), [CatalogModifierList](#type-catalogmodifierlist),
[CatalogModifier](#type-catalogmodifier)).

For example, a query that should return Items may specify attribute names from
any of the searchable fields of the [CatalogItem](#type-catalogitem) data type, namely
`"name"`, `"description"`, and `"abbreviation"`. | +| `limit` | `Integer` | Optional | A limit on the number of results to be returned in a single page. The limit is advisory -
the implementation may return more or fewer results. If the supplied limit is negative, zero, or
is higher than the maximum limit of 1,000, it will be ignored. | + +### Example (as JSON) + +```json +{ + "object_types": [ + "ITEM" + ], + "query": { + "prefix_query": { + "attribute_name": "name", + "attribute_prefix": "tea" + } + }, + "limit": 100 +} +``` + diff --git a/doc/models/search-catalog-objects-response.md b/doc/models/search-catalog-objects-response.md index ae55e931..fd395ccd 100644 --- a/doc/models/search-catalog-objects-response.md +++ b/doc/models/search-catalog-objects-response.md @@ -1,118 +1,119 @@ -## Search Catalog Objects Response - -### Structure - -`SearchCatalogObjectsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset, this is the final response.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `objects` | [`Array`](/doc/models/catalog-object.md) | Optional | The [CatalogObject](./models/catalog-object.md)s returned. | -| `related_objects` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](./models/catalog-object.md)s referenced by the objects in the `objects` field. | - -### Example (as JSON) - -```json -{ - "objects": [ - { - "type": "ITEM", - "id": "X5DZ5NWWAQ44CKBLKIFQGOWK", - "updated_at": "2017-10-26T15:41:32.337Z", - "version": 1509032492337, - "is_deleted": false, - "present_at_all_locations": true, - "item_data": { - "name": "Tea - Black", - "description": "A delicious blend of black tea.", - "category_id": "E7CLE5RZZ744BHWVQQEAHI2C", - "product_type": "REGULAR", - "tax_ids": [ - "ZXITPM6RWHZ7GZ7EIP3YKECM" - ], - "variations": [ - { - "type": "ITEM_VARIATION", - "id": "5GSZPX6EU7MM75S57OONG3V5", - "updated_at": "2017-10-26T15:27:31.626Z", - "version": 1509031651626, - "is_deleted": false, - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "X5DZ5NWWAQ44CKBLKIFQGOWK", - "name": "Regular", - "ordinal": 1, - "price_money": { - "amount": 150, - "currency": "USD" - }, - "pricing_type": "FIXED_PRICING" - } - }, - { - "type": "ITEM_VARIATION", - "id": "XVLBN7DU6JTWHJTG5F265B43", - "updated_at": "2017-10-26T15:27:31.626Z", - "version": 1509031651626, - "is_deleted": false, - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "X5DZ5NWWAQ44CKBLKIFQGOWK", - "name": "Large", - "ordinal": 2, - "price_money": { - "amount": 225, - "currency": "USD" - }, - "pricing_type": "FIXED_PRICING" - } - } - ], - "visibility": "PRIVATE" - } - }, - { - "type": "ITEM", - "id": "NNNEM3LA656Q46NXLWCNI7S5", - "updated_at": "2017-10-26T15:41:23.232Z", - "version": 1509032483232, - "is_deleted": false, - "present_at_all_locations": true, - "item_data": { - "name": "Tea - Green", - "description": "Relaxing green herbal tea.", - "category_id": "E7CLE5RZZ744BHWVQQEAHI2C", - "product_type": "REGULAR", - "tax_ids": [ - "ZXITPM6RWHZ7GZ7EIP3YKECM" - ], - "variations": [ - { - "type": "ITEM_VARIATION", - "id": "FHYBVIA6NVBCSOVETA62WEA4", - "updated_at": "2017-10-26T15:29:00.524Z", - "version": 1509031740524, - "is_deleted": false, - "present_at_all_locations": true, - "item_variation_data": { - "item_id": "NNNEM3LA656Q46NXLWCNI7S5", - "name": "Regular", - "ordinal": 1, - "price_money": { - "amount": 150, - "currency": "USD" - }, - "pricing_type": "FIXED_PRICING" - } - } - ], - "visibility": "PRIVATE" - } - } - ] -} -``` - +## Search Catalog Objects Response + +### Structure + +`SearchCatalogObjectsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset, this is the final response.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `objects` | [`Array`](/doc/models/catalog-object.md) | Optional | The [CatalogObject](#type-catalogobject)s returned. | +| `related_objects` | [`Array`](/doc/models/catalog-object.md) | Optional | A list of [CatalogObject](#type-catalogobject)s referenced by the objects in the `objects` field. | +| `latest_time` | `String` | Optional | When this merchant's catalog was last updated. Will match the value for `end_time` or `cursor` if
either field is included in the `SearchCatalog` request. | + +### Example (as JSON) + +```json +{ + "objects": [ + { + "type": "ITEM", + "id": "X5DZ5NWWAQ44CKBLKIFQGOWK", + "updated_at": "2017-10-26T15:41:32.337Z", + "version": 1509032492337, + "is_deleted": false, + "present_at_all_locations": true, + "item_data": { + "name": "Tea - Black", + "description": "A delicious blend of black tea.", + "category_id": "E7CLE5RZZ744BHWVQQEAHI2C", + "product_type": "REGULAR", + "tax_ids": [ + "ZXITPM6RWHZ7GZ7EIP3YKECM" + ], + "variations": [ + { + "type": "ITEM_VARIATION", + "id": "5GSZPX6EU7MM75S57OONG3V5", + "updated_at": "2017-10-26T15:27:31.626Z", + "version": 1509031651626, + "is_deleted": false, + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "X5DZ5NWWAQ44CKBLKIFQGOWK", + "name": "Regular", + "ordinal": 1, + "price_money": { + "amount": 150, + "currency": "USD" + }, + "pricing_type": "FIXED_PRICING" + } + }, + { + "type": "ITEM_VARIATION", + "id": "XVLBN7DU6JTWHJTG5F265B43", + "updated_at": "2017-10-26T15:27:31.626Z", + "version": 1509031651626, + "is_deleted": false, + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "X5DZ5NWWAQ44CKBLKIFQGOWK", + "name": "Large", + "ordinal": 2, + "price_money": { + "amount": 225, + "currency": "USD" + }, + "pricing_type": "FIXED_PRICING" + } + } + ], + "visibility": "PRIVATE" + } + }, + { + "type": "ITEM", + "id": "NNNEM3LA656Q46NXLWCNI7S5", + "updated_at": "2017-10-26T15:41:23.232Z", + "version": 1509032483232, + "is_deleted": false, + "present_at_all_locations": true, + "item_data": { + "name": "Tea - Green", + "description": "Relaxing green herbal tea.", + "category_id": "E7CLE5RZZ744BHWVQQEAHI2C", + "product_type": "REGULAR", + "tax_ids": [ + "ZXITPM6RWHZ7GZ7EIP3YKECM" + ], + "variations": [ + { + "type": "ITEM_VARIATION", + "id": "FHYBVIA6NVBCSOVETA62WEA4", + "updated_at": "2017-10-26T15:29:00.524Z", + "version": 1509031740524, + "is_deleted": false, + "present_at_all_locations": true, + "item_variation_data": { + "item_id": "NNNEM3LA656Q46NXLWCNI7S5", + "name": "Regular", + "ordinal": 1, + "price_money": { + "amount": 150, + "currency": "USD" + }, + "pricing_type": "FIXED_PRICING" + } + } + ], + "visibility": "PRIVATE" + } + } + ] +} +``` + diff --git a/doc/models/search-customers-request.md b/doc/models/search-customers-request.md index 2afad711..79a1ea2e 100644 --- a/doc/models/search-customers-request.md +++ b/doc/models/search-customers-request.md @@ -1,43 +1,43 @@ -## Search Customers Request - -Defines the fields included in the request body for the -SearchCustomers endpoint. - -### Structure - -`SearchCustomersRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `cursor` | `String` | Optional | Include the pagination cursor in subsequent calls to this endpoint to retrieve
the next set of results associated with the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `limit` | `Long` | Optional | A limit on the number of results to be returned in a single page.
The limit is advisory - the implementation may return more or fewer results.
If the supplied limit is negative, zero, or is higher than the maximum limit
of 1,000, it will be ignored. | -| `query` | [`Customer Query Hash`](/doc/models/customer-query.md) | Optional | Represents a query (filtering and sorting criteria) used to search
for customer profiles. | - -### Example (as JSON) - -```json -{ - "query": { - "filter": { - "creation_source": { - "values": [ - "THIRD_PARTY" - ], - "rule": "INCLUDE" - }, - "created_at": { - "start_at": "2018-01-01T00:00:00-00:00", - "end_at": "2018-02-01T00:00:00-00:00" - } - }, - "sort": { - "field": "CREATED_AT", - "order": "ASC" - } - }, - "limit": 2 -} -``` - +## Search Customers Request + +Defines the fields included in the request body for the +SearchCustomers endpoint. + +### Structure + +`SearchCustomersRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `cursor` | `String` | Optional | Include the pagination cursor in subsequent calls to this endpoint to retrieve
the next set of results associated with the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `limit` | `Long` | Optional | A limit on the number of results to be returned in a single page.
The limit is advisory - the implementation may return more or fewer results.
If the supplied limit is negative, zero, or is higher than the maximum limit
of 1,000, it will be ignored. | +| `query` | [`Customer Query Hash`](/doc/models/customer-query.md) | Optional | Represents a query (filtering and sorting criteria) used to search
for customer profiles. | + +### Example (as JSON) + +```json +{ + "query": { + "filter": { + "creation_source": { + "values": [ + "THIRD_PARTY" + ], + "rule": "INCLUDE" + }, + "created_at": { + "start_at": "2018-01-01T00:00:00-00:00", + "end_at": "2018-02-01T00:00:00-00:00" + } + }, + "sort": { + "field": "CREATED_AT", + "order": "ASC" + } + }, + "limit": 2 +} +``` + diff --git a/doc/models/search-customers-response.md b/doc/models/search-customers-response.md index e7ec2759..698f06c9 100644 --- a/doc/models/search-customers-response.md +++ b/doc/models/search-customers-response.md @@ -1,68 +1,68 @@ -## Search Customers Response - -Defines the fields that are included in the response body of -a request to the SearchCustomers endpoint. - -One of `errors` or `customers` is present in a given response (never both). - -### Structure - -`SearchCustomersResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `customers` | [`Array`](/doc/models/customer.md) | Optional | An array of `Customer` objects that match a query. | -| `cursor` | `String` | Optional | A pagination cursor that can be used during subsequent calls
to SearchCustomers to retrieve the next set of results associated
with the original query. Pagination cursors are only present when
a request succeeds and additional results are available.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | - -### Example (as JSON) - -```json -{ - "customers": [ - { - "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", - "created_at": "2018-01-23T20:21:54.859Z", - "updated_at": "2018-04-20T10:02:43.083Z", - "given_name": "James", - "family_name": "Bond", - "email_address": "james.bond@example.com", - "address": { - "address_line_1": "505 Electric Ave", - "address_line_2": "Suite 600", - "locality": "New York", - "administrative_district_level_1": "NY", - "postal_code": "10003", - "country": "US" - }, - "phone_number": "1-212-555-4250", - "reference_id": "YOUR_REFERENCE_ID_2", - "creation_source": "THIRD_PARTY" - }, - { - "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", - "created_at": "2018-01-30T14:10:54.859Z", - "updated_at": "2018-03-08T18:25:54.859Z", - "given_name": "Amelia", - "family_name": "Earhart", - "email_address": "amelia.earhart@example.com", - "address": { - "address_line_1": "500 Electric Ave", - "address_line_2": "Suite 600", - "locality": "New York", - "administrative_district_level_1": "NY", - "postal_code": "10003", - "country": "US" - }, - "phone_number": "1-212-555-4240", - "reference_id": "YOUR_REFERENCE_ID_1", - "note": "a customer", - "creation_source": "THIRD_PARTY" - } - ], - "cursor": "9dpS093Uy12AzeE" -} -``` - +## Search Customers Response + +Defines the fields that are included in the response body of +a request to the SearchCustomers endpoint. + +One of `errors` or `customers` is present in a given response (never both). + +### Structure + +`SearchCustomersResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `customers` | [`Array`](/doc/models/customer.md) | Optional | An array of `Customer` objects that match a query. | +| `cursor` | `String` | Optional | A pagination cursor that can be used during subsequent calls
to SearchCustomers to retrieve the next set of results associated
with the original query. Pagination cursors are only present when
a request succeeds and additional results are available.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Example (as JSON) + +```json +{ + "customers": [ + { + "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", + "created_at": "2018-01-23T20:21:54.859Z", + "updated_at": "2018-04-20T10:02:43.083Z", + "given_name": "James", + "family_name": "Bond", + "email_address": "james.bond@example.com", + "address": { + "address_line_1": "505 Electric Ave", + "address_line_2": "Suite 600", + "locality": "New York", + "administrative_district_level_1": "NY", + "postal_code": "10003", + "country": "US" + }, + "phone_number": "1-212-555-4250", + "reference_id": "YOUR_REFERENCE_ID_2", + "creation_source": "THIRD_PARTY" + }, + { + "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", + "created_at": "2018-01-30T14:10:54.859Z", + "updated_at": "2018-03-08T18:25:54.859Z", + "given_name": "Amelia", + "family_name": "Earhart", + "email_address": "amelia.earhart@example.com", + "address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "locality": "New York", + "administrative_district_level_1": "NY", + "postal_code": "10003", + "country": "US" + }, + "phone_number": "1-212-555-4240", + "reference_id": "YOUR_REFERENCE_ID_1", + "note": "a customer", + "creation_source": "THIRD_PARTY" + } + ], + "cursor": "9dpS093Uy12AzeE" +} +``` + diff --git a/doc/models/search-orders-customer-filter.md b/doc/models/search-orders-customer-filter.md index bca231c3..b653651f 100644 --- a/doc/models/search-orders-customer-filter.md +++ b/doc/models/search-orders-customer-filter.md @@ -1,24 +1,24 @@ -## Search Orders Customer Filter - +## Search Orders Customer Filter + Filter based on Order `customer_id` and any Tender `customer_id` associated with the Order. Does not filter based on the -[FulfillmentRecipient](./models/fulfillment-recipient.md) `customer_id`. - -### Structure - -`SearchOrdersCustomerFilter` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `customer_ids` | `Array` | Optional | Filter by orders with any of the listed `customer_id`s.

Max: 10 `customer_id`s. | - -### Example (as JSON) - -```json -{ - "customer_ids": null -} -``` - +[FulfillmentRecipient](#type-orderfulfillmentrecipient) `customer_id`. + +### Structure + +`SearchOrdersCustomerFilter` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `customer_ids` | `Array` | Optional | List of customer IDs to filter by.

Max: 10 customer IDs. | + +### Example (as JSON) + +```json +{ + "customer_ids": null +} +``` + diff --git a/doc/models/search-orders-date-time-filter.md b/doc/models/search-orders-date-time-filter.md index 577a521a..997c7605 100644 --- a/doc/models/search-orders-date-time-filter.md +++ b/doc/models/search-orders-date-time-filter.md @@ -1,37 +1,39 @@ -## Search Orders Date Time Filter - -Filter for `Order` objects based on whether their `CREATED_AT`, -`CLOSED_AT` or `UPDATED_AT` timestamps fall within a specified time range. -You can specify the time range and which timestamp to filter for. You can filter -for only one time range at a time. - -For each time range, the start time and end time are inclusive. If the end time -is absent, it defaults to the time of the first request for the cursor. - -__Important:__ If you use the DateTimeFilter to filter for `CLOSED_AT` or `UPDATED_AT`, -you must also set the [OrdersSort](./models/orders-sort.md). -The TimeRange used in DateTimeFilter must correspond to the `sort_field` in -the [OrdersSort](./models/orders-sort.md) object. - -### Structure - -`SearchOrdersDateTimeFilter` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `created_at` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | -| `updated_at` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | -| `closed_at` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | - -### Example (as JSON) - -```json -{ - "created_at": null, - "updated_at": null, - "closed_at": null -} -``` - +## Search Orders Date Time Filter + +Filter for `Order` objects based on whether their `CREATED_AT`, +`CLOSED_AT` or `UPDATED_AT` timestamps fall within a specified time range. +You can specify the time range and which timestamp to filter for. You can filter +for only one time range at a time. + +For each time range, the start time and end time are inclusive. If the end time +is absent, it defaults to the time of the first request for the cursor. + +__Important:__ If you use the DateTimeFilter in a SearchOrders query, +you must also set the `sort_field` in [OrdersSort](#type-searchorderordersort) +to the same field you filter for. For example, if you set the `CLOSED_AT` field +in DateTimeFilter, you must also set the `sort_field` in SearchOrdersSort to +`CLOSED_AT`. Otherwise, SearchOrders will throw an error. +[Learn more about filtering orders by time range](https://developer.squareup.com/docs/orders-api/manage-orders#important-note-on-filtering-orders-by-time-range). + +### Structure + +`SearchOrdersDateTimeFilter` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `created_at` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | +| `updated_at` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | +| `closed_at` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | + +### Example (as JSON) + +```json +{ + "created_at": null, + "updated_at": null, + "closed_at": null +} +``` + diff --git a/doc/models/search-orders-filter.md b/doc/models/search-orders-filter.md index 6c15de4e..a0949b49 100644 --- a/doc/models/search-orders-filter.md +++ b/doc/models/search-orders-filter.md @@ -1,30 +1,31 @@ -## Search Orders Filter - -Filter options to use for a query. Multiple filters will be ANDed together. - -### Structure - -`SearchOrdersFilter` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `state_filter` | [`Search Orders State Filter Hash`](/doc/models/search-orders-state-filter.md) | Optional | Filter by current Order `state`. | -| `date_time_filter` | [`Search Orders Date Time Filter Hash`](/doc/models/search-orders-date-time-filter.md) | Optional | Filter for `Order` objects based on whether their `CREATED_AT`,
`CLOSED_AT` or `UPDATED_AT` timestamps fall within a specified time range.
You can specify the time range and which timestamp to filter for. You can filter
for only one time range at a time.

For each time range, the start time and end time are inclusive. If the end time
is absent, it defaults to the time of the first request for the cursor.

__Important:__ If you use the DateTimeFilter to filter for `CLOSED_AT` or `UPDATED_AT`,
you must also set the [OrdersSort](./models/orders-sort.md).
The TimeRange used in DateTimeFilter must correspond to the `sort_field` in
the [OrdersSort](./models/orders-sort.md) object. | -| `fulfillment_filter` | [`Search Orders Fulfillment Filter Hash`](/doc/models/search-orders-fulfillment-filter.md) | Optional | Filter based on [Order Fulfillment](#type-orderfulfillment) information. | -| `source_filter` | [`Search Orders Source Filter Hash`](/doc/models/search-orders-source-filter.md) | Optional | Filter based on Order `source` information. | -| `customer_filter` | [`Search Orders Customer Filter Hash`](/doc/models/search-orders-customer-filter.md) | Optional | Filter based on Order `customer_id` and any Tender `customer_id`
associated with the Order. Does not filter based on the
[FulfillmentRecipient](./models/fulfillment-recipient.md) `customer_id`. | - -### Example (as JSON) - -```json -{ - "state_filter": null, - "date_time_filter": null, - "fulfillment_filter": null, - "source_filter": null, - "customer_filter": null -} -``` - +## Search Orders Filter + +Filtering criteria to use for a SearchOrders request. Multiple filters +will be ANDed together. + +### Structure + +`SearchOrdersFilter` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `state_filter` | [`Search Orders State Filter Hash`](/doc/models/search-orders-state-filter.md) | Optional | Filter by current Order `state`. | +| `date_time_filter` | [`Search Orders Date Time Filter Hash`](/doc/models/search-orders-date-time-filter.md) | Optional | Filter for `Order` objects based on whether their `CREATED_AT`,
`CLOSED_AT` or `UPDATED_AT` timestamps fall within a specified time range.
You can specify the time range and which timestamp to filter for. You can filter
for only one time range at a time.

For each time range, the start time and end time are inclusive. If the end time
is absent, it defaults to the time of the first request for the cursor.

__Important:__ If you use the DateTimeFilter in a SearchOrders query,
you must also set the `sort_field` in [OrdersSort](#type-searchorderordersort)
to the same field you filter for. For example, if you set the `CLOSED_AT` field
in DateTimeFilter, you must also set the `sort_field` in SearchOrdersSort to
`CLOSED_AT`. Otherwise, SearchOrders will throw an error.
[Learn more about filtering orders by time range](https://developer.squareup.com/docs/orders-api/manage-orders#important-note-on-filtering-orders-by-time-range). | +| `fulfillment_filter` | [`Search Orders Fulfillment Filter Hash`](/doc/models/search-orders-fulfillment-filter.md) | Optional | Filter based on [Order Fulfillment](#type-orderfulfillment) information. | +| `source_filter` | [`Search Orders Source Filter Hash`](/doc/models/search-orders-source-filter.md) | Optional | Filter based on order `source` information. | +| `customer_filter` | [`Search Orders Customer Filter Hash`](/doc/models/search-orders-customer-filter.md) | Optional | Filter based on Order `customer_id` and any Tender `customer_id`
associated with the Order. Does not filter based on the
[FulfillmentRecipient](#type-orderfulfillmentrecipient) `customer_id`. | + +### Example (as JSON) + +```json +{ + "state_filter": null, + "date_time_filter": null, + "fulfillment_filter": null, + "source_filter": null, + "customer_filter": null +} +``` + diff --git a/doc/models/search-orders-fulfillment-filter.md b/doc/models/search-orders-fulfillment-filter.md index 551f44ec..fcaf8ec6 100644 --- a/doc/models/search-orders-fulfillment-filter.md +++ b/doc/models/search-orders-fulfillment-filter.md @@ -1,27 +1,27 @@ -## Search Orders Fulfillment Filter - -Filter based on [Order Fulfillment](#type-orderfulfillment) information. - -### Structure - -`SearchOrdersFulfillmentFilter` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `fulfillment_types` | [`Array`](/doc/models/order-fulfillment-type.md) | | List of [fulfillment types](./models/order-fulfillment-type.md) to filter
for. Will return orders if any of its fulfillments match any of the fulfillment types
listed in this field.
See [OrderFulfillmentType](#type-orderfulfillmenttype) for possible values | -| `fulfillment_states` | [`Array`](/doc/models/order-fulfillment-state.md) | Optional | List of [fulfillment states](./models/order-fulfillment-state.md) to filter
for. Will return orders if any of its fulfillments match any of the
fulfillment states listed in this field.
See [OrderFulfillmentState](./models/order-fulfillment-state.md) for possible values | - -### Example (as JSON) - -```json -{ - "fulfillment_types": [ - "SHIPMENT", - "PICKUP" - ], - "fulfillment_states": null -} -``` - +## Search Orders Fulfillment Filter + +Filter based on [Order Fulfillment](#type-orderfulfillment) information. + +### Structure + +`SearchOrdersFulfillmentFilter` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `fulfillment_types` | [`Array`](/doc/models/order-fulfillment-type.md) | | List of [fulfillment types](#type-orderfulfillmenttype) to filter
for. Will return orders if any of its fulfillments match any of the fulfillment types
listed in this field.
See [OrderFulfillmentType](#type-orderfulfillmenttype) for possible values | +| `fulfillment_states` | [`Array`](/doc/models/order-fulfillment-state.md) | Optional | List of [fulfillment states](#type-orderfulfillmentstate) to filter
for. Will return orders if any of its fulfillments match any of the
fulfillment states listed in this field.
See [OrderFulfillmentState](#type-orderfulfillmentstate) for possible values | + +### Example (as JSON) + +```json +{ + "fulfillment_types": [ + "SHIPMENT", + "PICKUP" + ], + "fulfillment_states": null +} +``` + diff --git a/doc/models/search-orders-query.md b/doc/models/search-orders-query.md index fe7a2005..de316994 100644 --- a/doc/models/search-orders-query.md +++ b/doc/models/search-orders-query.md @@ -1,24 +1,24 @@ -## Search Orders Query - -Contains query criteria for the search. - -### Structure - -`SearchOrdersQuery` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `filter` | [`Search Orders Filter Hash`](/doc/models/search-orders-filter.md) | Optional | Filter options to use for a query. Multiple filters will be ANDed together. | -| `sort` | [`Search Orders Sort Hash`](/doc/models/search-orders-sort.md) | Optional | Sorting options for a query. Returned Orders will always be sorted on a timestamp. | - -### Example (as JSON) - -```json -{ - "filter": null, - "sort": null -} -``` - +## Search Orders Query + +Contains query criteria for the search. + +### Structure + +`SearchOrdersQuery` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `filter` | [`Search Orders Filter Hash`](/doc/models/search-orders-filter.md) | Optional | Filtering criteria to use for a SearchOrders request. Multiple filters
will be ANDed together. | +| `sort` | [`Search Orders Sort Hash`](/doc/models/search-orders-sort.md) | Optional | Sorting criteria for a SearchOrders request. Results can only be sorted
by a timestamp field. | + +### Example (as JSON) + +```json +{ + "filter": null, + "sort": null +} +``` + diff --git a/doc/models/search-orders-request.md b/doc/models/search-orders-request.md index acd5bc44..cd4a91ff 100644 --- a/doc/models/search-orders-request.md +++ b/doc/models/search-orders-request.md @@ -1,53 +1,53 @@ -## Search Orders Request - -The request does not have any required fields. When given no query criteria, -SearchOrders will return all results for all of the merchant’s locations. When fetching additional -pages using a `cursor`, the `query` must be equal to the `query` used to fetch the first page of -results. - -### Structure - -`SearchOrdersRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_ids` | `Array` | Optional | The location IDs for the orders to query. The caller must have access to
all provided locations. Leave unset to search all locations that the caller has access to. | -| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `query` | [`Search Orders Query Hash`](/doc/models/search-orders-query.md) | Optional | Contains query criteria for the search. | -| `limit` | `Integer` | Optional | Number of results to be returned in a single page. SearchOrders may
use a smaller limit than specified depending on server load. If the response
includes a `cursor` field, you can use it to retrieve the next set of results.
Default: `500` | -| `return_entries` | `Boolean` | Optional | If set to `true`, SearchOrders will return [`OrderEntry`](#type-orderentry)
objects instead of `Order` objects. `OrderEntry` objects are lightweight
descriptions of orders that include `order_id`s.

Default: `false`. | - -### Example (as JSON) - -```json -{ - "return_entries": true, - "limit": 3, - "location_ids": [ - "057P5VYJ4A5X1", - "18YC4JDH91E1H" - ], - "query": { - "filter": { - "date_time_filter": { - "closed_at": { - "start_at": "2018-03-03T20:00:00+00:00", - "end_at": "2019-03-04T21:54:45+00:00" - } - }, - "state_filter": { - "states": [ - "COMPLETED" - ] - } - }, - "sort": { - "sort_field": "CLOSED_AT", - "sort_order": "DESC" - } - } -} -``` - +## Search Orders Request + +The request does not have any required fields. When given no query criteria, +SearchOrders will return all results for all of the merchant’s locations. When fetching additional +pages using a `cursor`, the `query` must be equal to the `query` used to fetch the first page of +results. + +### Structure + +`SearchOrdersRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_ids` | `Array` | Optional | The location IDs for the orders to query. All locations must belong to
the same merchant.

Min: 1 location IDs.

Max: 10 location IDs. | +| `cursor` | `String` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `query` | [`Search Orders Query Hash`](/doc/models/search-orders-query.md) | Optional | Contains query criteria for the search. | +| `limit` | `Integer` | Optional | Maximum number of results to be returned in a single page. It is
possible to receive fewer results than the specified limit on a given page.

Default: `500` | +| `return_entries` | `Boolean` | Optional | Boolean that controls the format of the search results. If `true`,
SearchOrders will return [`OrderEntry`](#type-orderentry) objects. If `false`, SearchOrders
will return complete Order objects.

Default: `false`. | + +### Example (as JSON) + +```json +{ + "return_entries": true, + "limit": 3, + "location_ids": [ + "057P5VYJ4A5X1", + "18YC4JDH91E1H" + ], + "query": { + "filter": { + "date_time_filter": { + "closed_at": { + "start_at": "2018-03-03T20:00:00+00:00", + "end_at": "2019-03-04T21:54:45+00:00" + } + }, + "state_filter": { + "states": [ + "COMPLETED" + ] + } + }, + "sort": { + "sort_field": "CLOSED_AT", + "sort_order": "DESC" + } + } +} +``` + diff --git a/doc/models/search-orders-response.md b/doc/models/search-orders-response.md index 345002d7..9f220f51 100644 --- a/doc/models/search-orders-response.md +++ b/doc/models/search-orders-response.md @@ -1,40 +1,41 @@ -## Search Orders Response - -Only one of `order_entries` or `orders` fields will be set, depending on whether -`return_entries` was set on the [SearchOrdersRequest](./models/search-orders-request.md). - -### Structure - -`SearchOrdersResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order_entries` | [`Array`](/doc/models/order-entry.md) | Optional | List of [OrderEntries](./models/order-entries.md) that fit the query
conditions. Populated only if `order_entries` was set to `true` in the request. | -| `orders` | [`Array`](/doc/models/order.md) | Optional | List of
[Orders](./models/orders.md) that match query conditions. Populated only if
`return_entries` in the request is set to `false`. | -| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | [Errors](./models/errors.md) encountered during the search. | - -### Example (as JSON) - -```json -{ - "order_entries": [ - { - "id": "CAISEM82RcpmcFBM0TfOyiHV3es", - "location_id": "057P5VYJ4A5X1" - }, - { - "id": "CAISENgvlJ6jLWAzERDzjyHVybY", - "location_id": "18YC4JDH91E1H" - }, - { - "id": "CAISEM52YcpmcWAzERDOyiWS3ty", - "location_id": "057P5VYJ4A5X1" - } - ], - "cursor": "123" -} -``` - +## Search Orders Response + +Only one of `order_entries` or `orders` fields will be set, depending on whether +`return_entries` was set on the [SearchOrdersRequest](#type-searchorderrequest). + +### Structure + +`SearchOrdersResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order_entries` | [`Array`](/doc/models/order-entry.md) | Optional | List of [OrderEntries](#type-orderentry) that fit the query
conditions. Populated only if `return_entries` was set to `true` in the request. | +| `orders` | [`Array`](/doc/models/order.md) | Optional | List of
[Order](#type-order) objects that match query conditions. Populated only if
`return_entries` in the request is set to `false`. | +| `cursor` | `String` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | [Errors](#type-error) encountered during the search. | + +### Example (as JSON) + +```json +{ + "order_entries": [ + { + "order_id": "CAISEM82RcpmcFBM0TfOyiHV3es", + "location_id": "057P5VYJ4A5X1", + "version": 1 + }, + { + "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY", + "location_id": "18YC4JDH91E1H" + }, + { + "order_id": "CAISEM52YcpmcWAzERDOyiWS3ty", + "location_id": "057P5VYJ4A5X1" + } + ], + "cursor": "123" +} +``` + diff --git a/doc/models/search-orders-sort-field.md b/doc/models/search-orders-sort-field.md index 6e82e4dd..d93d38e3 100644 --- a/doc/models/search-orders-sort-field.md +++ b/doc/models/search-orders-sort-field.md @@ -1,16 +1,16 @@ -## Search Orders Sort Field - -Specifies which timestamp to use to sort SearchOrder results. - -### Enumeration - -`SearchOrdersSortField` - -### Fields - -| Name | Description | -| --- | --- | -| `CREATED_AT` | Time when the order was created in RFC-3339 format. | -| `UPDATED_AT` | Time when the order last updated in RFC-3339 format. | -| `CLOSED_AT` | Time when the order was closed in RFC-3339 format. | - +## Search Orders Sort Field + +Specifies which timestamp to use to sort SearchOrder results. + +### Enumeration + +`SearchOrdersSortField` + +### Fields + +| Name | Description | +| --- | --- | +| `CREATED_AT` | Time when the order was created in RFC-3339 format. If you are also
filtering for a time range in this query, you must set the `CREATED_AT`
field in your DateTimeFilter. | +| `UPDATED_AT` | Time when the order last updated in RFC-3339 format. If you are also
filtering for a time range in this query, you must set the `UPDATED_AT`
field in your DateTimeFilter. | +| `CLOSED_AT` | Time when the order was closed in RFC-3339 format. If you use this
value, you must also set a StateFilter with closed states. If you are also
filtering for a time range in this query, you must set the `CLOSED_AT`
field in your DateTimeFilter. | + diff --git a/doc/models/search-orders-sort.md b/doc/models/search-orders-sort.md index 01a27b92..e5f9f1db 100644 --- a/doc/models/search-orders-sort.md +++ b/doc/models/search-orders-sort.md @@ -1,24 +1,25 @@ -## Search Orders Sort - -Sorting options for a query. Returned Orders will always be sorted on a timestamp. - -### Structure - -`SearchOrdersSort` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `sort_field` | [`String (Search Orders Sort Field)`](/doc/models/search-orders-sort-field.md) | | Specifies which timestamp to use to sort SearchOrder results. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | - -### Example (as JSON) - -```json -{ - "sort_field": "CLOSED_AT", - "sort_order": null -} -``` - +## Search Orders Sort + +Sorting criteria for a SearchOrders request. Results can only be sorted +by a timestamp field. + +### Structure + +`SearchOrdersSort` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `sort_field` | [`String (Search Orders Sort Field)`](/doc/models/search-orders-sort-field.md) | | Specifies which timestamp to use to sort SearchOrder results. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | + +### Example (as JSON) + +```json +{ + "sort_field": "CLOSED_AT", + "sort_order": null +} +``` + diff --git a/doc/models/search-orders-source-filter.md b/doc/models/search-orders-source-filter.md index 57e1526e..627f5e3f 100644 --- a/doc/models/search-orders-source-filter.md +++ b/doc/models/search-orders-source-filter.md @@ -1,22 +1,22 @@ -## Search Orders Source Filter - -Filter based on Order `source` information. - -### Structure - -`SearchOrdersSourceFilter` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `source_names` | `Array` | Optional | Filters by [Source](./models/source.md) `name`. Will return any orders
with with `source.name`s that match any of the listed source names.

Max: 10 `source_names`. | - -### Example (as JSON) - -```json -{ - "source_names": null -} -``` - +## Search Orders Source Filter + +Filter based on order `source` information. + +### Structure + +`SearchOrdersSourceFilter` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `source_names` | `Array` | Optional | Filters by [Source](#type-ordersource) `name`. Will return any orders
with with a `source.name` that matches any of the listed source names.

Max: 10 source names. | + +### Example (as JSON) + +```json +{ + "source_names": null +} +``` + diff --git a/doc/models/search-orders-state-filter.md b/doc/models/search-orders-state-filter.md index bfc98409..1ef88ee2 100644 --- a/doc/models/search-orders-state-filter.md +++ b/doc/models/search-orders-state-filter.md @@ -1,25 +1,25 @@ -## Search Orders State Filter - -Filter by current Order `state`. - -### Structure - -`SearchOrdersStateFilter` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `states` | [`Array`](/doc/models/order-state.md) | States to filter for.
See [OrderState](./models/order-state.md) for possible values | - -### Example (as JSON) - -```json -{ - "states": [ - "CANCELED", - "OPEN" - ] -} -``` - +## Search Orders State Filter + +Filter by current Order `state`. + +### Structure + +`SearchOrdersStateFilter` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `states` | [`Array`](/doc/models/order-state.md) | States to filter for.
See [OrderState](#type-orderstate) for possible values | + +### Example (as JSON) + +```json +{ + "states": [ + "CANCELED", + "OPEN" + ] +} +``` + diff --git a/doc/models/search-shifts-request.md b/doc/models/search-shifts-request.md index 7e127b35..0bd01b3e 100644 --- a/doc/models/search-shifts-request.md +++ b/doc/models/search-shifts-request.md @@ -1,36 +1,36 @@ -## Search Shifts Request - -A request for a filtered and sorted set of `Shift` objects. - -### Structure - -`SearchShiftsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `query` | [`Shift Query Hash`](/doc/models/shift-query.md) | Optional | The parameters of a `Shift` search query. Includes filter and sort options. | -| `limit` | `Integer` | Optional | number of resources in a page (200 by default). | -| `cursor` | `String` | Optional | opaque cursor for fetching the next page. | - -### Example (as JSON) - -```json -{ - "query": { - "filter": { - "workday": { - "date_range": { - "start_date": "2019-01-20", - "end_date": "2019-02-03" - }, - "match_shifts_by": "START_AT", - "default_timezone": "America/Los_Angeles" - } - } - }, - "limit": 100 -} -``` - +## Search Shifts Request + +A request for a filtered and sorted set of `Shift` objects. + +### Structure + +`SearchShiftsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `query` | [`Shift Query Hash`](/doc/models/shift-query.md) | Optional | The parameters of a `Shift` search query. Includes filter and sort options. | +| `limit` | `Integer` | Optional | number of resources in a page (200 by default). | +| `cursor` | `String` | Optional | opaque cursor for fetching the next page. | + +### Example (as JSON) + +```json +{ + "query": { + "filter": { + "workday": { + "date_range": { + "start_date": "2019-01-20", + "end_date": "2019-02-03" + }, + "match_shifts_by": "START_AT", + "default_timezone": "America/Los_Angeles" + } + } + }, + "limit": 100 +} +``` + diff --git a/doc/models/search-shifts-response.md b/doc/models/search-shifts-response.md index d61026c1..d05fa1a8 100644 --- a/doc/models/search-shifts-response.md +++ b/doc/models/search-shifts-response.md @@ -1,96 +1,96 @@ -## Search Shifts Response - -The response to a request for `Shift` objects. Contains -the requested `Shift` objects. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`SearchShiftsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `shifts` | [`Array`](/doc/models/shift.md) | Optional | Shifts | -| `cursor` | `String` | Optional | Opaque cursor for fetching the next page. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "shifts": [ - { - "id": "X714F3HA6D1PT", - "employee_id": "ormj0jJJZ5OZIzxrZYJI", - "location_id": "PAA1RJZZKXBFG", - "timezone": "America/New_York", - "start_at": "2019-01-21T03:11:00-05:00", - "end_at": "2019-01-21T13:11:00-05:00", - "wage": { - "title": "Barista", - "hourly_rate": { - "amount": 1100, - "currency": "USD" - } - }, - "breaks": [ - { - "id": "SJW7X6AKEJQ65", - "start_at": "2019-01-21T06:11:00-05:00", - "end_at": "2019-01-21T06:11:00-05:00", - "break_type_id": "REGS1EQR1TPZ5", - "name": "Tea Break", - "expected_duration": "PT10M", - "is_paid": true - } - ], - "status": "CLOSED", - "version": 6, - "created_at": "2019-01-24T01:12:03Z", - "updated_at": "2019-02-07T22:21:08Z" - }, - { - "id": "GDHYBZYWK0P2V", - "employee_id": "33fJchumvVdJwxV0H6L9", - "location_id": "PAA1RJZZKXBFG", - "timezone": "America/New_York", - "start_at": "2019-01-22T12:02:00-05:00", - "end_at": "2019-01-22T13:02:00-05:00", - "wage": { - "title": "Cook", - "hourly_rate": { - "amount": 1600, - "currency": "USD" - } - }, - "breaks": [ - { - "id": "BKS6VR7WR748A", - "start_at": "2019-01-23T14:30:00-05:00", - "end_at": "2019-01-23T14:40:00-05:00", - "break_type_id": "WQX00VR99F53J", - "name": "Tea Break", - "expected_duration": "PT10M", - "is_paid": true - }, - { - "id": "BQFEZSHFZSC51", - "start_at": "2019-01-22T12:30:00-05:00", - "end_at": "2019-01-22T12:44:00-05:00", - "break_type_id": "P6Q468ZFRN1AC", - "name": "Coffee Break", - "expected_duration": "PT15M", - "is_paid": false - } - ], - "status": "CLOSED", - "version": 16, - "created_at": "2019-01-23T23:32:45Z", - "updated_at": "2019-01-24T00:56:25Z" - } - ] -} -``` - +## Search Shifts Response + +The response to a request for `Shift` objects. Contains +the requested `Shift` objects. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`SearchShiftsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `shifts` | [`Array`](/doc/models/shift.md) | Optional | Shifts | +| `cursor` | `String` | Optional | Opaque cursor for fetching the next page. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "shifts": [ + { + "id": "X714F3HA6D1PT", + "employee_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "timezone": "America/New_York", + "start_at": "2019-01-21T03:11:00-05:00", + "end_at": "2019-01-21T13:11:00-05:00", + "wage": { + "title": "Barista", + "hourly_rate": { + "amount": 1100, + "currency": "USD" + } + }, + "breaks": [ + { + "id": "SJW7X6AKEJQ65", + "start_at": "2019-01-21T06:11:00-05:00", + "end_at": "2019-01-21T06:11:00-05:00", + "break_type_id": "REGS1EQR1TPZ5", + "name": "Tea Break", + "expected_duration": "PT10M", + "is_paid": true + } + ], + "status": "CLOSED", + "version": 6, + "created_at": "2019-01-24T01:12:03Z", + "updated_at": "2019-02-07T22:21:08Z" + }, + { + "id": "GDHYBZYWK0P2V", + "employee_id": "33fJchumvVdJwxV0H6L9", + "location_id": "PAA1RJZZKXBFG", + "timezone": "America/New_York", + "start_at": "2019-01-22T12:02:00-05:00", + "end_at": "2019-01-22T13:02:00-05:00", + "wage": { + "title": "Cook", + "hourly_rate": { + "amount": 1600, + "currency": "USD" + } + }, + "breaks": [ + { + "id": "BKS6VR7WR748A", + "start_at": "2019-01-23T14:30:00-05:00", + "end_at": "2019-01-23T14:40:00-05:00", + "break_type_id": "WQX00VR99F53J", + "name": "Tea Break", + "expected_duration": "PT10M", + "is_paid": true + }, + { + "id": "BQFEZSHFZSC51", + "start_at": "2019-01-22T12:30:00-05:00", + "end_at": "2019-01-22T12:44:00-05:00", + "break_type_id": "P6Q468ZFRN1AC", + "name": "Coffee Break", + "expected_duration": "PT15M", + "is_paid": false + } + ], + "status": "CLOSED", + "version": 16, + "created_at": "2019-01-23T23:32:45Z", + "updated_at": "2019-01-24T00:56:25Z" + } + ] +} +``` + diff --git a/doc/models/shift-filter-status.md b/doc/models/shift-filter-status.md index da775c0c..481f30c3 100644 --- a/doc/models/shift-filter-status.md +++ b/doc/models/shift-filter-status.md @@ -1,15 +1,15 @@ -## Shift Filter Status - -Specifies the `status` of `Shift` records to be returned. - -### Enumeration - -`ShiftFilterStatus` - -### Fields - -| Name | Description | -| --- | --- | -| `OPEN` | Shifts that have been started and not ended. | -| `CLOSED` | Shifts that have been started and ended. | - +## Shift Filter Status + +Specifies the `status` of `Shift` records to be returned. + +### Enumeration + +`ShiftFilterStatus` + +### Fields + +| Name | Description | +| --- | --- | +| `OPEN` | Shifts that have been started and not ended. | +| `CLOSED` | Shifts that have been started and ended. | + diff --git a/doc/models/shift-filter.md b/doc/models/shift-filter.md index 6b92f143..153e8190 100644 --- a/doc/models/shift-filter.md +++ b/doc/models/shift-filter.md @@ -1,33 +1,33 @@ -## Shift Filter - -Defines a filter used in a search for `Shift` records. `AND` logic is -used by Square's servers to apply each filter property specified. - -### Structure - -`ShiftFilter` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `Array` | Optional | Fetch shifts for the specified location. | -| `employee_id` | `Array` | Optional | Fetch shifts for the specified employee. | -| `status` | [`String (Shift Filter Status)`](/doc/models/shift-filter-status.md) | Optional | Specifies the `status` of `Shift` records to be returned. | -| `start` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | -| `end` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | -| `workday` | [`Shift Workday Hash`](/doc/models/shift-workday.md) | Optional | A `Shift` search query filter parameter that sets a range of days that
a `Shift` must start or end in before passing the filter condition. | - -### Example (as JSON) - -```json -{ - "location_id": null, - "employee_id": null, - "status": null, - "start": null, - "end": null, - "workday": null -} -``` - +## Shift Filter + +Defines a filter used in a search for `Shift` records. `AND` logic is +used by Square's servers to apply each filter property specified. + +### Structure + +`ShiftFilter` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `Array` | Optional | Fetch shifts for the specified location. | +| `employee_id` | `Array` | Optional | Fetch shifts for the specified employee. | +| `status` | [`String (Shift Filter Status)`](/doc/models/shift-filter-status.md) | Optional | Specifies the `status` of `Shift` records to be returned. | +| `start` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | +| `end` | [`Time Range Hash`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC-3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevent endpoint-specific documentation to determine
how time ranges are handled. | +| `workday` | [`Shift Workday Hash`](/doc/models/shift-workday.md) | Optional | A `Shift` search query filter parameter that sets a range of days that
a `Shift` must start or end in before passing the filter condition. | + +### Example (as JSON) + +```json +{ + "location_id": null, + "employee_id": null, + "status": null, + "start": null, + "end": null, + "workday": null +} +``` + diff --git a/doc/models/shift-query.md b/doc/models/shift-query.md index 0295eb5d..7afaf3da 100644 --- a/doc/models/shift-query.md +++ b/doc/models/shift-query.md @@ -1,24 +1,24 @@ -## Shift Query - -The parameters of a `Shift` search query. Includes filter and sort options. - -### Structure - -`ShiftQuery` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `filter` | [`Shift Filter Hash`](/doc/models/shift-filter.md) | Optional | Defines a filter used in a search for `Shift` records. `AND` logic is
used by Square's servers to apply each filter property specified. | -| `sort` | [`Shift Sort Hash`](/doc/models/shift-sort.md) | Optional | Sets the sort order of search results. | - -### Example (as JSON) - -```json -{ - "filter": null, - "sort": null -} -``` - +## Shift Query + +The parameters of a `Shift` search query. Includes filter and sort options. + +### Structure + +`ShiftQuery` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `filter` | [`Shift Filter Hash`](/doc/models/shift-filter.md) | Optional | Defines a filter used in a search for `Shift` records. `AND` logic is
used by Square's servers to apply each filter property specified. | +| `sort` | [`Shift Sort Hash`](/doc/models/shift-sort.md) | Optional | Sets the sort order of search results. | + +### Example (as JSON) + +```json +{ + "filter": null, + "sort": null +} +``` + diff --git a/doc/models/shift-sort-field.md b/doc/models/shift-sort-field.md index 47193b65..1e00b1d7 100644 --- a/doc/models/shift-sort-field.md +++ b/doc/models/shift-sort-field.md @@ -1,17 +1,17 @@ -## Shift Sort Field - -Enumerates the `Shift` fields to sort on. - -### Enumeration - -`ShiftSortField` - -### Fields - -| Name | Description | -| --- | --- | -| `START_AT` | The start date/time of a `Shift` | -| `END_AT` | The end date/time of a `Shift` | -| `CREATED_AT` | The date/time that a `Shift` is created | -| `UPDATED_AT` | The most recent date/time that a `Shift` is updated | - +## Shift Sort Field + +Enumerates the `Shift` fields to sort on. + +### Enumeration + +`ShiftSortField` + +### Fields + +| Name | Description | +| --- | --- | +| `START_AT` | The start date/time of a `Shift` | +| `END_AT` | The end date/time of a `Shift` | +| `CREATED_AT` | The date/time that a `Shift` is created | +| `UPDATED_AT` | The most recent date/time that a `Shift` is updated | + diff --git a/doc/models/shift-sort.md b/doc/models/shift-sort.md index afaa7161..fa765c70 100644 --- a/doc/models/shift-sort.md +++ b/doc/models/shift-sort.md @@ -1,24 +1,24 @@ -## Shift Sort - -Sets the sort order of search results. - -### Structure - -`ShiftSort` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `field` | [`String (Shift Sort Field)`](/doc/models/shift-sort-field.md) | Optional | Enumerates the `Shift` fields to sort on. | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | - -### Example (as JSON) - -```json -{ - "field": null, - "order": null -} -``` - +## Shift Sort + +Sets the sort order of search results. + +### Structure + +`ShiftSort` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `field` | [`String (Shift Sort Field)`](/doc/models/shift-sort-field.md) | Optional | Enumerates the `Shift` fields to sort on. | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | + +### Example (as JSON) + +```json +{ + "field": null, + "order": null +} +``` + diff --git a/doc/models/shift-status.md b/doc/models/shift-status.md index c8744f6c..6761e72e 100644 --- a/doc/models/shift-status.md +++ b/doc/models/shift-status.md @@ -1,15 +1,15 @@ -## Shift Status - -Enumerates the possible status of a `Shift` - -### Enumeration - -`ShiftStatus` - -### Fields - -| Name | Description | -| --- | --- | -| `OPEN` | Employee started a work shift and the shift is not complete | -| `CLOSED` | Employee started and ended a work shift. | - +## Shift Status + +Enumerates the possible status of a `Shift` + +### Enumeration + +`ShiftStatus` + +### Fields + +| Name | Description | +| --- | --- | +| `OPEN` | Employee started a work shift and the shift is not complete | +| `CLOSED` | Employee started and ended a work shift. | + diff --git a/doc/models/shift-wage.md b/doc/models/shift-wage.md index 2681bf54..c87b6761 100644 --- a/doc/models/shift-wage.md +++ b/doc/models/shift-wage.md @@ -1,24 +1,24 @@ -## Shift Wage - -The hourly wage rate used to compensate an employee for this shift. - -### Structure - -`ShiftWage` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `title` | `String` | Optional | The name of the job performed during this shift. Square
labor-reporting UIs may group shifts together by title. | -| `hourly_rate` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "title": null, - "hourly_rate": null -} -``` - +## Shift Wage + +The hourly wage rate used to compensate an employee for this shift. + +### Structure + +`ShiftWage` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `title` | `String` | Optional | The name of the job performed during this shift. Square
labor-reporting UIs may group shifts together by title. | +| `hourly_rate` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "title": null, + "hourly_rate": null +} +``` + diff --git a/doc/models/shift-workday-matcher.md b/doc/models/shift-workday-matcher.md index caad6e27..7c3ec04b 100644 --- a/doc/models/shift-workday-matcher.md +++ b/doc/models/shift-workday-matcher.md @@ -1,16 +1,16 @@ -## Shift Workday Matcher - -Defines the logic used to apply a workday filter. - -### Enumeration - -`ShiftWorkdayMatcher` - -### Fields - -| Name | Description | -| --- | --- | -| `START_AT` | All shifts that start on or after the specified workday | -| `END_AT` | All shifts that end on or before the specified workday | -| `INTERSECTION` | All shifts that start between the start and end workdays (inclusive) | - +## Shift Workday Matcher + +Defines the logic used to apply a workday filter. + +### Enumeration + +`ShiftWorkdayMatcher` + +### Fields + +| Name | Description | +| --- | --- | +| `START_AT` | All shifts that start on or after the specified workday | +| `END_AT` | All shifts that end on or before the specified workday | +| `INTERSECTION` | All shifts that start between the start and end workdays (inclusive) | + diff --git a/doc/models/shift-workday.md b/doc/models/shift-workday.md index e7bfd881..3d093699 100644 --- a/doc/models/shift-workday.md +++ b/doc/models/shift-workday.md @@ -1,27 +1,27 @@ -## Shift Workday - -A `Shift` search query filter parameter that sets a range of days that -a `Shift` must start or end in before passing the filter condition. - -### Structure - -`ShiftWorkday` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `date_range` | [`Date Range Hash`](/doc/models/date-range.md) | Optional | A range defined by two dates. Used for filtering a query for Connect v2
objects that have date properties. | -| `match_shifts_by` | [`String (Shift Workday Matcher)`](/doc/models/shift-workday-matcher.md) | Optional | Defines the logic used to apply a workday filter. | -| `default_timezone` | `String` | Optional | Location-specific timezones convert workdays to datetime filters.
Every location included in the query must have a timezone, or this field
must be provided as a fallback. Format: the IANA timezone database
identifier for the relevant timezone. | - -### Example (as JSON) - -```json -{ - "date_range": null, - "match_shifts_by": null, - "default_timezone": null -} -``` - +## Shift Workday + +A `Shift` search query filter parameter that sets a range of days that +a `Shift` must start or end in before passing the filter condition. + +### Structure + +`ShiftWorkday` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `date_range` | [`Date Range Hash`](/doc/models/date-range.md) | Optional | A range defined by two dates. Used for filtering a query for Connect v2
objects that have date properties. | +| `match_shifts_by` | [`String (Shift Workday Matcher)`](/doc/models/shift-workday-matcher.md) | Optional | Defines the logic used to apply a workday filter. | +| `default_timezone` | `String` | Optional | Location-specific timezones convert workdays to datetime filters.
Every location included in the query must have a timezone, or this field
must be provided as a fallback. Format: the IANA timezone database
identifier for the relevant timezone. | + +### Example (as JSON) + +```json +{ + "date_range": null, + "match_shifts_by": null, + "default_timezone": null +} +``` + diff --git a/doc/models/shift.md b/doc/models/shift.md index 98688cbe..13a589a0 100644 --- a/doc/models/shift.md +++ b/doc/models/shift.md @@ -1,46 +1,46 @@ -## Shift - -A record of the hourly rate, start, and end times for a single work shift -for an employee. May include a record of the start and end times for breaks -taken during the shift. - -### Structure - -`Shift` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | UUID for this object | -| `employee_id` | `String` | | The ID of the employee this shift belongs to. | -| `location_id` | `String` | Optional | The ID of the location this shift occurred at. Should be based on
where the employee clocked in. | -| `timezone` | `String` | Optional | Read-only convenience value that is calculated from the location based
on `location_id`. Format: the IANA Timezone Database identifier for the
location timezone. | -| `start_at` | `String` | | RFC 3339; shifted to location timezone + offset. Precision up to the
minute is respected; seconds are truncated. | -| `end_at` | `String` | Optional | RFC 3339; shifted to timezone + offset. Precision up to the minute is
respected; seconds are truncated. The `end_at` minute is not
counted when the shift length is calculated. For example, a shift from `00:00`
to `08:01` is considered an 8 hour shift (midnight to 8am). | -| `wage` | [`Shift Wage Hash`](/doc/models/shift-wage.md) | Optional | The hourly wage rate used to compensate an employee for this shift. | -| `breaks` | [`Array`](/doc/models/break.md) | Optional | A list of any paid or unpaid breaks that were taken during this shift. | -| `status` | [`String (Shift Status)`](/doc/models/shift-status.md) | Optional | Enumerates the possible status of a `Shift` | -| `version` | `Integer` | Optional | Used for resolving concurrency issues; request will fail if version
provided does not match server version at time of request. If not provided,
Square executes a blind write; potentially overwriting data from another
write. | -| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC. | -| `updated_at` | `String` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC. | - -### Example (as JSON) - -```json -{ - "id": null, - "employee_id": "employee_id0", - "location_id": null, - "timezone": null, - "start_at": "start_at2", - "end_at": null, - "wage": null, - "breaks": null, - "status": null, - "version": null, - "created_at": null, - "updated_at": null -} -``` - +## Shift + +A record of the hourly rate, start, and end times for a single work shift +for an employee. May include a record of the start and end times for breaks +taken during the shift. + +### Structure + +`Shift` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | UUID for this object | +| `employee_id` | `String` | | The ID of the employee this shift belongs to. | +| `location_id` | `String` | Optional | The ID of the location this shift occurred at. Should be based on
where the employee clocked in. | +| `timezone` | `String` | Optional | Read-only convenience value that is calculated from the location based
on `location_id`. Format: the IANA Timezone Database identifier for the
location timezone. | +| `start_at` | `String` | | RFC 3339; shifted to location timezone + offset. Precision up to the
minute is respected; seconds are truncated. | +| `end_at` | `String` | Optional | RFC 3339; shifted to timezone + offset. Precision up to the minute is
respected; seconds are truncated. The `end_at` minute is not
counted when the shift length is calculated. For example, a shift from `00:00`
to `08:01` is considered an 8 hour shift (midnight to 8am). | +| `wage` | [`Shift Wage Hash`](/doc/models/shift-wage.md) | Optional | The hourly wage rate used to compensate an employee for this shift. | +| `breaks` | [`Array`](/doc/models/break.md) | Optional | A list of any paid or unpaid breaks that were taken during this shift. | +| `status` | [`String (Shift Status)`](/doc/models/shift-status.md) | Optional | Enumerates the possible status of a `Shift` | +| `version` | `Integer` | Optional | Used for resolving concurrency issues; request will fail if version
provided does not match server version at time of request. If not provided,
Square executes a blind write; potentially overwriting data from another
write. | +| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC. | +| `updated_at` | `String` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC. | + +### Example (as JSON) + +```json +{ + "id": null, + "employee_id": "employee_id0", + "location_id": null, + "timezone": null, + "start_at": "start_at2", + "end_at": null, + "wage": null, + "breaks": null, + "status": null, + "version": null, + "created_at": null, + "updated_at": null +} +``` + diff --git a/doc/models/sort-order.md b/doc/models/sort-order.md index 86814536..1eb4a23a 100644 --- a/doc/models/sort-order.md +++ b/doc/models/sort-order.md @@ -1,15 +1,15 @@ -## Sort Order - -The order (e.g., chronological or alphabetical) in which results from a request are returned. - -### Enumeration - -`SortOrder` - -### Fields - -| Name | Description | -| --- | --- | -| `DESC` | The results are returned in descending (e.g., newest-first or Z-A) order. | -| `ASC` | The results are returned in ascending (e.g., oldest-first or A-Z) order. | - +## Sort Order + +The order (e.g., chronological or alphabetical) in which results from a request are returned. + +### Enumeration + +`SortOrder` + +### Fields + +| Name | Description | +| --- | --- | +| `DESC` | The results are returned in descending (e.g., newest-first or Z-A) order. | +| `ASC` | The results are returned in ascending (e.g., oldest-first or A-Z) order. | + diff --git a/doc/models/source-application.md b/doc/models/source-application.md index b36b5ecd..77c99fe7 100644 --- a/doc/models/source-application.md +++ b/doc/models/source-application.md @@ -1,27 +1,27 @@ -## Source Application - -Provides information about the application used to generate an inventory -change. - -### Structure - -`SourceApplication` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `product` | [`String (Product)`](/doc/models/product.md) | Optional | Indicates the Square product used to generate an inventory change. | -| `application_id` | `String` | Optional | Read-only Square ID assigned to the application. Only used for
[Product](./models/product.md) type `EXTERNAL_API`. | -| `name` | `String` | Optional | Read-only display name assigned to the application
(e.g. `"Custom Application"`, `"Square POS 4.74 for Android"`). | - -### Example (as JSON) - -```json -{ - "product": null, - "application_id": null, - "name": null -} -``` - +## Source Application + +Provides information about the application used to generate an inventory +change. + +### Structure + +`SourceApplication` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `product` | [`String (Product)`](/doc/models/product.md) | Optional | Indicates the Square product used to generate an inventory change. | +| `application_id` | `String` | Optional | Read-only Square ID assigned to the application. Only used for
[Product](#type-product) type `EXTERNAL_API`. | +| `name` | `String` | Optional | Read-only display name assigned to the application
(e.g. `"Custom Application"`, `"Square POS 4.74 for Android"`). | + +### Example (as JSON) + +```json +{ + "product": null, + "application_id": null, + "name": null +} +``` + diff --git a/doc/models/standard-unit-description-group.md b/doc/models/standard-unit-description-group.md index 4b9fd6fb..4322b734 100644 --- a/doc/models/standard-unit-description-group.md +++ b/doc/models/standard-unit-description-group.md @@ -1,24 +1,24 @@ -## Standard Unit Description Group - -Group of standard measurement units. - -### Structure - -`StandardUnitDescriptionGroup` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `standard_unit_descriptions` | [`Array`](/doc/models/standard-unit-description.md) | Optional | List of measurement units in this description group. | -| `language_code` | `String` | Optional | IETF language tag. | - -### Example (as JSON) - -```json -{ - "standard_unit_descriptions": null, - "language_code": null -} -``` - +## Standard Unit Description Group + +Group of standard measurement units. + +### Structure + +`StandardUnitDescriptionGroup` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `standard_unit_descriptions` | [`Array`](/doc/models/standard-unit-description.md) | Optional | List of measurement units in this description group. | +| `language_code` | `String` | Optional | IETF language tag. | + +### Example (as JSON) + +```json +{ + "standard_unit_descriptions": null, + "language_code": null +} +``` + diff --git a/doc/models/standard-unit-description.md b/doc/models/standard-unit-description.md index 55f519ab..bca0c562 100644 --- a/doc/models/standard-unit-description.md +++ b/doc/models/standard-unit-description.md @@ -1,26 +1,26 @@ -## Standard Unit Description - -Contains the name and abbreviation for standard measurement unit. - -### Structure - -`StandardUnitDescription` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `unit` | [`Measurement Unit Hash`](/doc/models/measurement-unit.md) | Optional | Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required: `custom_unit`,
`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`.

The `family` field describes the type of measurement. For example,
ounces are in the weight family. | -| `name` | `String` | Optional | Display name of the measurement unit. For example, 'Pound'. | -| `abbreviation` | `String` | Optional | Abbreviation for the measurement unit. For example, 'lb'. | - -### Example (as JSON) - -```json -{ - "unit": null, - "name": null, - "abbreviation": null -} -``` - +## Standard Unit Description + +Contains the name and abbreviation for standard measurement unit. + +### Structure + +`StandardUnitDescription` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `unit` | [`Measurement Unit Hash`](/doc/models/measurement-unit.md) | Optional | Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required: `custom_unit`,
`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`. | +| `name` | `String` | Optional | Display name of the measurement unit. For example, 'Pound'. | +| `abbreviation` | `String` | Optional | Abbreviation for the measurement unit. For example, 'lb'. | + +### Example (as JSON) + +```json +{ + "unit": null, + "name": null, + "abbreviation": null +} +``` + diff --git a/doc/models/tax-calculation-phase.md b/doc/models/tax-calculation-phase.md index 727deb36..a7be52e7 100644 --- a/doc/models/tax-calculation-phase.md +++ b/doc/models/tax-calculation-phase.md @@ -1,15 +1,15 @@ -## Tax Calculation Phase - -When to calculate the taxes due on a cart. - -### Enumeration - -`TaxCalculationPhase` - -### Fields - -| Name | Description | -| --- | --- | -| `TAX_SUBTOTAL_PHASE` | The fee is calculated based on the payment's subtotal. | -| `TAX_TOTAL_PHASE` | The fee is calculated based on the payment's total. | - +## Tax Calculation Phase + +When to calculate the taxes due on a cart. + +### Enumeration + +`TaxCalculationPhase` + +### Fields + +| Name | Description | +| --- | --- | +| `TAX_SUBTOTAL_PHASE` | The fee is calculated based on the payment's subtotal. | +| `TAX_TOTAL_PHASE` | The fee is calculated based on the payment's total. | + diff --git a/doc/models/tax-inclusion-type.md b/doc/models/tax-inclusion-type.md index 178f64d4..4117b5da 100644 --- a/doc/models/tax-inclusion-type.md +++ b/doc/models/tax-inclusion-type.md @@ -1,15 +1,15 @@ -## Tax Inclusion Type - -Whether to the tax amount should be additional to or included in to the [CatalogItem](./models/catalog-item.md) price. - -### Enumeration - -`TaxInclusionType` - -### Fields - -| Name | Description | -| --- | --- | -| `ADDITIVE` | The tax is an additive tax. The tax amount is added on top of the
[CatalogItemVariation](./models/catalog-item-variation.md) price. For example, a $1.00 item with a 10% additive
tax would have a total cost to the buyer of $1.10. | -| `INCLUSIVE` | The tax is an inclusive tax. The tax amount is included in the
[CatalogItemVariation](./models/catalog-item-variation.md) price. For example, a $1.00 item with a 10% inclusive
tax would have a total cost to the buyer of $1.00, with $0.91 (91 cents) of that total being the cost of the item
and $0.09 (9 cents) being tax. | - +## Tax Inclusion Type + +Whether to the tax amount should be additional to or included in to the [CatalogItem](#type-catalogitem) price. + +### Enumeration + +`TaxInclusionType` + +### Fields + +| Name | Description | +| --- | --- | +| `ADDITIVE` | The tax is an additive tax. The tax amount is added on top of the
[CatalogItemVariation](#type-catalogitemvariation) price. For example, a $1.00 item with a 10% additive
tax would have a total cost to the buyer of $1.10. | +| `INCLUSIVE` | The tax is an inclusive tax. The tax amount is included in the
[CatalogItemVariation](#type-catalogitemvariation) price. For example, a $1.00 item with a 10% inclusive
tax would have a total cost to the buyer of $1.00, with $0.91 (91 cents) of that total being the cost of the item
and $0.09 (9 cents) being tax. | + diff --git a/doc/models/tender-card-details-entry-method.md b/doc/models/tender-card-details-entry-method.md index 9a01a37a..0221ff82 100644 --- a/doc/models/tender-card-details-entry-method.md +++ b/doc/models/tender-card-details-entry-method.md @@ -1,18 +1,18 @@ -## Tender Card Details Entry Method - -Indicates the method used to enter the card's details. - -### Enumeration - -`TenderCardDetailsEntryMethod` - -### Fields - -| Name | Description | -| --- | --- | -| `SWIPED` | The card was swiped through a Square reader or Square stand. | -| `KEYED` | The card information was keyed manually into Square Point of Sale or a
Square-hosted web form. | -| `EMV` | The card was processed via EMV with a Square reader. | -| `ON_FILE` | The buyer's card details were already on file with Square. | -| `CONTACTLESS` | The card was processed via a contactless (i.e., NFC) transaction
with a Square reader. | - +## Tender Card Details Entry Method + +Indicates the method used to enter the card's details. + +### Enumeration + +`TenderCardDetailsEntryMethod` + +### Fields + +| Name | Description | +| --- | --- | +| `SWIPED` | The card was swiped through a Square reader or Square stand. | +| `KEYED` | The card information was keyed manually into Square Point of Sale or a
Square-hosted web form. | +| `EMV` | The card was processed via EMV with a Square reader. | +| `ON_FILE` | The buyer's card details were already on file with Square. | +| `CONTACTLESS` | The card was processed via a contactless (i.e., NFC) transaction
with a Square reader. | + diff --git a/doc/models/tender-card-details-status.md b/doc/models/tender-card-details-status.md index 569e07d1..d3f400e1 100644 --- a/doc/models/tender-card-details-status.md +++ b/doc/models/tender-card-details-status.md @@ -1,17 +1,17 @@ -## Tender Card Details Status - -Indicates the card transaction's current status. - -### Enumeration - -`TenderCardDetailsStatus` - -### Fields - -| Name | Description | -| --- | --- | -| `AUTHORIZED` | The card transaction has been authorized but not yet captured. | -| `CAPTURED` | The card transaction was authorized and subsequently captured (i.e., completed). | -| `VOIDED` | The card transaction was authorized and subsequently voided (i.e., canceled). | -| `FAILED` | The card transaction failed. | - +## Tender Card Details Status + +Indicates the card transaction's current status. + +### Enumeration + +`TenderCardDetailsStatus` + +### Fields + +| Name | Description | +| --- | --- | +| `AUTHORIZED` | The card transaction has been authorized but not yet captured. | +| `CAPTURED` | The card transaction was authorized and subsequently captured (i.e., completed). | +| `VOIDED` | The card transaction was authorized and subsequently voided (i.e., canceled). | +| `FAILED` | The card transaction failed. | + diff --git a/doc/models/tender-card-details.md b/doc/models/tender-card-details.md index 121d4c59..2a29b78d 100644 --- a/doc/models/tender-card-details.md +++ b/doc/models/tender-card-details.md @@ -1,26 +1,26 @@ -## Tender Card Details - -Represents additional details of a tender with `type` `CARD` or `SQUARE_GIFT_CARD` - -### Structure - -`TenderCardDetails` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `status` | [`String (Tender Card Details Status)`](/doc/models/tender-card-details-status.md) | Optional | Indicates the card transaction's current status. | -| `card` | [`Card Hash`](/doc/models/card.md) | Optional | Represents the payment details of a card to be used for payments. These
details are determined by the `card_nonce` generated by `SqPaymentForm`. | -| `entry_method` | [`String (Tender Card Details Entry Method)`](/doc/models/tender-card-details-entry-method.md) | Optional | Indicates the method used to enter the card's details. | - -### Example (as JSON) - -```json -{ - "status": null, - "card": null, - "entry_method": null -} -``` - +## Tender Card Details + +Represents additional details of a tender with `type` `CARD` or `SQUARE_GIFT_CARD` + +### Structure + +`TenderCardDetails` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `status` | [`String (Tender Card Details Status)`](/doc/models/tender-card-details-status.md) | Optional | Indicates the card transaction's current status. | +| `card` | [`Card Hash`](/doc/models/card.md) | Optional | Represents the payment details of a card to be used for payments. These
details are determined by the `card_nonce` generated by `SqPaymentForm`. | +| `entry_method` | [`String (Tender Card Details Entry Method)`](/doc/models/tender-card-details-entry-method.md) | Optional | Indicates the method used to enter the card's details. | + +### Example (as JSON) + +```json +{ + "status": null, + "card": null, + "entry_method": null +} +``` + diff --git a/doc/models/tender-cash-details.md b/doc/models/tender-cash-details.md index 807ebc24..aaefe501 100644 --- a/doc/models/tender-cash-details.md +++ b/doc/models/tender-cash-details.md @@ -1,24 +1,24 @@ -## Tender Cash Details - -Represents the details of a tender with `type` `CASH`. - -### Structure - -`TenderCashDetails` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `buyer_tendered_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `change_back_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | - -### Example (as JSON) - -```json -{ - "buyer_tendered_money": null, - "change_back_money": null -} -``` - +## Tender Cash Details + +Represents the details of a tender with `type` `CASH`. + +### Structure + +`TenderCashDetails` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `buyer_tendered_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `change_back_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | + +### Example (as JSON) + +```json +{ + "buyer_tendered_money": null, + "change_back_money": null +} +``` + diff --git a/doc/models/tender-type.md b/doc/models/tender-type.md index a395b5d2..2fcb8ec0 100644 --- a/doc/models/tender-type.md +++ b/doc/models/tender-type.md @@ -1,19 +1,19 @@ -## Tender Type - -Indicates a tender's type. - -### Enumeration - -`TenderType` - -### Fields - -| Name | Description | -| --- | --- | -| `CARD` | A credit card. | -| `CASH` | Cash. | -| `THIRD_PARTY_CARD` | A credit card processed with a card processor other than Square.

This value applies only to merchants in countries where Square does not
yet provide card processing. | -| `SQUARE_GIFT_CARD` | A Square gift card. | -| `NO_SALE` | This tender represents the register being opened for a "no sale" event. | -| `OTHER` | A form of tender that does not match any other value. | - +## Tender Type + +Indicates a tender's type. + +### Enumeration + +`TenderType` + +### Fields + +| Name | Description | +| --- | --- | +| `CARD` | A credit card. | +| `CASH` | Cash. | +| `THIRD_PARTY_CARD` | A credit card processed with a card processor other than Square.

This value applies only to merchants in countries where Square does not
yet provide card processing. | +| `SQUARE_GIFT_CARD` | A Square gift card. | +| `NO_SALE` | This tender represents the register being opened for a "no sale" event. | +| `OTHER` | A form of tender that does not match any other value. | + diff --git a/doc/models/tender.md b/doc/models/tender.md index 176608d6..4ee5794b 100644 --- a/doc/models/tender.md +++ b/doc/models/tender.md @@ -1,48 +1,48 @@ -## Tender - -Represents a tender (i.e., a method of payment) used in a Square transaction. - -### Structure - -`Tender` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The tender's unique ID. | -| `location_id` | `String` | Optional | The ID of the transaction's associated location. | -| `transaction_id` | `String` | Optional | The ID of the tender's associated transaction. | -| `created_at` | `String` | Optional | The time when the tender was created, in RFC 3339 format. | -| `note` | `String` | Optional | An optional note associated with the tender at the time of payment. | -| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `tip_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `processing_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money.

__Important:__ Unlike version 1 of the Connect API, __all monetary amounts
returned by v2 endpoints are positive.__ (In v1, monetary amounts are negative
if they represent money being paid _by_ a merchant, instead of money being
paid _to_ a merchant.) | -| `customer_id` | `String` | Optional | If the tender is associated with a customer or represents a customer's card on file,
this is the ID of the associated customer. | -| `type` | [`String (Tender Type)`](/doc/models/tender-type.md) | | Indicates a tender's type. | -| `card_details` | [`Tender Card Details Hash`](/doc/models/tender-card-details.md) | Optional | Represents additional details of a tender with `type` `CARD` or `SQUARE_GIFT_CARD` | -| `cash_details` | [`Tender Cash Details Hash`](/doc/models/tender-cash-details.md) | Optional | Represents the details of a tender with `type` `CASH`. | -| `additional_recipients` | [`Array`](/doc/models/additional-recipient.md) | Optional | Additional recipients (other than the merchant) receiving a portion of this tender.
For example, fees assessed on the purchase by a third party integration. | -| `payment_id` | `String` | Optional | The ID of the [Payment](./models/payment.md) that corresponds to this tender.
This value is only present for payments created with the v2 Payments API. | - -### Example (as JSON) - -```json -{ - "id": null, - "location_id": null, - "transaction_id": null, - "created_at": null, - "note": null, - "amount_money": null, - "tip_money": null, - "processing_fee_money": null, - "customer_id": null, - "type": "THIRD_PARTY_CARD", - "card_details": null, - "cash_details": null, - "additional_recipients": null, - "payment_id": null -} -``` - +## Tender + +Represents a tender (i.e., a method of payment) used in a Square transaction. + +### Structure + +`Tender` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The tender's unique ID. | +| `location_id` | `String` | Optional | The ID of the transaction's associated location. | +| `transaction_id` | `String` | Optional | The ID of the tender's associated transaction. | +| `created_at` | `String` | Optional | The time when the tender was created, in RFC 3339 format. | +| `note` | `String` | Optional | An optional note associated with the tender at the time of payment. | +| `amount_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `tip_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `processing_fee_money` | [`Money Hash`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned. | +| `customer_id` | `String` | Optional | If the tender is associated with a customer or represents a customer's card on file,
this is the ID of the associated customer. | +| `type` | [`String (Tender Type)`](/doc/models/tender-type.md) | | Indicates a tender's type. | +| `card_details` | [`Tender Card Details Hash`](/doc/models/tender-card-details.md) | Optional | Represents additional details of a tender with `type` `CARD` or `SQUARE_GIFT_CARD` | +| `cash_details` | [`Tender Cash Details Hash`](/doc/models/tender-cash-details.md) | Optional | Represents the details of a tender with `type` `CASH`. | +| `additional_recipients` | [`Array`](/doc/models/additional-recipient.md) | Optional | Additional recipients (other than the merchant) receiving a portion of this tender.
For example, fees assessed on the purchase by a third party integration. | +| `payment_id` | `String` | Optional | The ID of the [Payment](#type-payment) that corresponds to this tender.
This value is only present for payments created with the v2 Payments API. | + +### Example (as JSON) + +```json +{ + "id": null, + "location_id": null, + "transaction_id": null, + "created_at": null, + "note": null, + "amount_money": null, + "tip_money": null, + "processing_fee_money": null, + "customer_id": null, + "type": "THIRD_PARTY_CARD", + "card_details": null, + "cash_details": null, + "additional_recipients": null, + "payment_id": null +} +``` + diff --git a/doc/models/time-range.md b/doc/models/time-range.md index bd078bc0..a00025b9 100644 --- a/doc/models/time-range.md +++ b/doc/models/time-range.md @@ -1,28 +1,28 @@ -## Time Range - +## Time Range + Represents a generic time range. The start and end values are represented in RFC-3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevent endpoint-specific documentation to determine -how time ranges are handled. - -### Structure - -`TimeRange` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `start_at` | `String` | Optional | A datetime value in RFC-3339 format indicating when the time range
starts. | -| `end_at` | `String` | Optional | A datetime value in RFC-3339 format indicating when the time range
ends. | - -### Example (as JSON) - -```json -{ - "start_at": null, - "end_at": null -} -``` - +how time ranges are handled. + +### Structure + +`TimeRange` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `start_at` | `String` | Optional | A datetime value in RFC-3339 format indicating when the time range
starts. | +| `end_at` | `String` | Optional | A datetime value in RFC-3339 format indicating when the time range
ends. | + +### Example (as JSON) + +```json +{ + "start_at": null, + "end_at": null +} +``` + diff --git a/doc/models/transaction-product.md b/doc/models/transaction-product.md index 58ed209f..0b5b08de 100644 --- a/doc/models/transaction-product.md +++ b/doc/models/transaction-product.md @@ -1,21 +1,21 @@ -## Transaction Product - -Indicates the Square product used to process a transaction. - -### Enumeration - -`TransactionProduct` - -### Fields - -| Name | Description | -| --- | --- | -| `REGISTER` | Square Point of Sale. | -| `EXTERNAL_API` | The Square Connect API. | -| `BILLING` | A Square subscription for one of multiple products. | -| `APPOINTMENTS` | Square Appointments. | -| `INVOICES` | Square Invoices. | -| `ONLINE_STORE` | Square Online Store. | -| `PAYROLL` | Square Payroll. | -| `OTHER` | A Square product that does not match any other value. | - +## Transaction Product + +Indicates the Square product used to process a transaction. + +### Enumeration + +`TransactionProduct` + +### Fields + +| Name | Description | +| --- | --- | +| `REGISTER` | Square Point of Sale. | +| `EXTERNAL_API` | The Square Connect API. | +| `BILLING` | A Square subscription for one of multiple products. | +| `APPOINTMENTS` | Square Appointments. | +| `INVOICES` | Square Invoices. | +| `ONLINE_STORE` | Square Online Store. | +| `PAYROLL` | Square Payroll. | +| `OTHER` | A Square product that does not match any other value. | + diff --git a/doc/models/transaction.md b/doc/models/transaction.md index dce27478..e68871a7 100644 --- a/doc/models/transaction.md +++ b/doc/models/transaction.md @@ -1,44 +1,44 @@ -## Transaction - -Represents a transaction processed with Square, either with the -Connect API or with Square Point of Sale. - -The `tenders` field of this object lists all methods of payment used to pay in -the transaction. - -### Structure - -`Transaction` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The transaction's unique ID, issued by Square payments servers. | -| `location_id` | `String` | Optional | The ID of the transaction's associated location. | -| `created_at` | `String` | Optional | The time when the transaction was created, in RFC 3339 format. | -| `tenders` | [`Array`](/doc/models/tender.md) | Optional | The tenders used to pay in the transaction. | -| `refunds` | [`Array`](/doc/models/refund.md) | Optional | Refunds that have been applied to any tender in the transaction. | -| `reference_id` | `String` | Optional | If the transaction was created with the [Charge](/doc/transactions.md#charge)
endpoint, this value is the same as the value provided for the `reference_id`
parameter in the request to that endpoint. Otherwise, it is not set. | -| `product` | [`String (Transaction Product)`](/doc/models/transaction-product.md) | Optional | Indicates the Square product used to process a transaction. | -| `client_id` | `String` | Optional | If the transaction was created in the Square Point of Sale app, this value
is the ID generated for the transaction by Square Point of Sale.

This ID has no relationship to the transaction's canonical `id`, which is
generated by Square's backend servers. This value is generated for bookkeeping
purposes, in case the transaction cannot immediately be completed (for example,
if the transaction is processed in offline mode).

It is not currently possible with the Connect API to perform a transaction
lookup by this value. | -| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `order_id` | `String` | Optional | The order_id is an identifier for the order associated with this transaction, if any. | - -### Example (as JSON) - -```json -{ - "id": null, - "location_id": null, - "created_at": null, - "tenders": null, - "refunds": null, - "reference_id": null, - "product": null, - "client_id": null, - "shipping_address": null, - "order_id": null -} -``` - +## Transaction + +Represents a transaction processed with Square, either with the +Connect API or with Square Point of Sale. + +The `tenders` field of this object lists all methods of payment used to pay in +the transaction. + +### Structure + +`Transaction` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The transaction's unique ID, issued by Square payments servers. | +| `location_id` | `String` | Optional | The ID of the transaction's associated location. | +| `created_at` | `String` | Optional | The time when the transaction was created, in RFC 3339 format. | +| `tenders` | [`Array`](/doc/models/tender.md) | Optional | The tenders used to pay in the transaction. | +| `refunds` | [`Array`](/doc/models/refund.md) | Optional | Refunds that have been applied to any tender in the transaction. | +| `reference_id` | `String` | Optional | If the transaction was created with the [Charge](#endpoint-transactions-charge)
endpoint, this value is the same as the value provided for the `reference_id`
parameter in the request to that endpoint. Otherwise, it is not set. | +| `product` | [`String (Transaction Product)`](/doc/models/transaction-product.md) | Optional | Indicates the Square product used to process a transaction. | +| `client_id` | `String` | Optional | If the transaction was created in the Square Point of Sale app, this value
is the ID generated for the transaction by Square Point of Sale.

This ID has no relationship to the transaction's canonical `id`, which is
generated by Square's backend servers. This value is generated for bookkeeping
purposes, in case the transaction cannot immediately be completed (for example,
if the transaction is processed in offline mode).

It is not currently possible with the Connect API to perform a transaction
lookup by this value. | +| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `order_id` | `String` | Optional | The order_id is an identifier for the order associated with this transaction, if any. | + +### Example (as JSON) + +```json +{ + "id": null, + "location_id": null, + "created_at": null, + "tenders": null, + "refunds": null, + "reference_id": null, + "product": null, + "client_id": null, + "shipping_address": null, + "order_id": null +} +``` + diff --git a/doc/models/update-break-type-request.md b/doc/models/update-break-type-request.md index ca482eff..09755e5b 100644 --- a/doc/models/update-break-type-request.md +++ b/doc/models/update-break-type-request.md @@ -1,28 +1,28 @@ -## Update Break Type Request - -A request to update a `BreakType` - -### Structure - -`UpdateBreakTypeRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `break_type` | [`Break Type Hash`](/doc/models/break-type.md) | Optional | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. | - -### Example (as JSON) - -```json -{ - "break_type": { - "location_id": "26M7H24AZ9N6R", - "break_name": "Lunch", - "expected_duration": "PT50M", - "is_paid": true, - "version": 1 - } -} -``` - +## Update Break Type Request + +A request to update a `BreakType` + +### Structure + +`UpdateBreakTypeRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `break_type` | [`Break Type Hash`](/doc/models/break-type.md) | Optional | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. | + +### Example (as JSON) + +```json +{ + "break_type": { + "location_id": "26M7H24AZ9N6R", + "break_name": "Lunch", + "expected_duration": "PT50M", + "is_paid": true, + "version": 1 + } +} +``` + diff --git a/doc/models/update-break-type-response.md b/doc/models/update-break-type-response.md index 6003c9fc..32d4f678 100644 --- a/doc/models/update-break-type-response.md +++ b/doc/models/update-break-type-response.md @@ -1,34 +1,34 @@ -## Update Break Type Response - -A response to a request to update a `BreakType`. Contains -the requested `BreakType` objects. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`UpdateBreakTypeResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `break_type` | [`Break Type Hash`](/doc/models/break-type.md) | Optional | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "break_type": { - "id": "Q6JSJS6D4DBCH", - "location_id": "26M7H24AZ9N6R", - "break_name": "Lunch", - "expected_duration": "PT50M", - "is_paid": true, - "version": 2, - "created_at": "2018-06-12T20:19:12Z", - "updated_at": "2019-02-26T23:12:59Z" - } -} -``` - +## Update Break Type Response + +A response to a request to update a `BreakType`. Contains +the requested `BreakType` objects. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`UpdateBreakTypeResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `break_type` | [`Break Type Hash`](/doc/models/break-type.md) | Optional | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "break_type": { + "id": "Q6JSJS6D4DBCH", + "location_id": "26M7H24AZ9N6R", + "break_name": "Lunch", + "expected_duration": "PT50M", + "is_paid": true, + "version": 2, + "created_at": "2018-06-12T20:19:12Z", + "updated_at": "2019-02-26T23:12:59Z" + } +} +``` + diff --git a/doc/models/update-customer-request.md b/doc/models/update-customer-request.md index ec91b2d5..a1c3efb2 100644 --- a/doc/models/update-customer-request.md +++ b/doc/models/update-customer-request.md @@ -1,34 +1,34 @@ -## Update Customer Request - -Defines the body parameters that can be provided in a request to the -UpdateCustomer endpoint. - -### Structure - -`UpdateCustomerRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `given_name` | `String` | Optional | The customer's given (i.e., first) name. | -| `family_name` | `String` | Optional | The customer's family (i.e., last) name. | -| `company_name` | `String` | Optional | The name of the customer's company. | -| `nickname` | `String` | Optional | A nickname for the customer. | -| `email_address` | `String` | Optional | The customer's email address. | -| `address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `phone_number` | `String` | Optional | The customer's phone number. | -| `reference_id` | `String` | Optional | An optional second ID you can set to associate the customer with an
entity in another system. | -| `note` | `String` | Optional | An optional note to associate with the customer. | -| `birthday` | `String` | Optional | The customer birthday in RFC-3339 format. Year is optional,
timezone and times are not allowed. Example: `0000-09-01T00:00:00-00:00`
for a birthday on September 1st. `1998-09-01T00:00:00-00:00` for a birthday
on September 1st 1998. | - -### Example (as JSON) - -```json -{ - "phone_number": "", - "email_address": "New.Amelia.Earhart@example.com", - "note": "updated customer note" -} -``` - +## Update Customer Request + +Defines the body parameters that can be provided in a request to the +UpdateCustomer endpoint. + +### Structure + +`UpdateCustomerRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `given_name` | `String` | Optional | The customer's given (i.e., first) name. | +| `family_name` | `String` | Optional | The customer's family (i.e., last) name. | +| `company_name` | `String` | Optional | The name of the customer's company. | +| `nickname` | `String` | Optional | A nickname for the customer. | +| `email_address` | `String` | Optional | The customer's email address. | +| `address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `phone_number` | `String` | Optional | The customer's phone number. | +| `reference_id` | `String` | Optional | An optional second ID you can set to associate the customer with an
entity in another system. | +| `note` | `String` | Optional | An optional note to associate with the customer. | +| `birthday` | `String` | Optional | The customer birthday in RFC-3339 format. Year is optional,
timezone and times are not allowed. Example: `0000-09-01T00:00:00-00:00`
for a birthday on September 1st. `1998-09-01T00:00:00-00:00` for a birthday
on September 1st 1998. | + +### Example (as JSON) + +```json +{ + "phone_number": "", + "email_address": "New.Amelia.Earhart@example.com", + "note": "updated customer note" +} +``` + diff --git a/doc/models/update-customer-response.md b/doc/models/update-customer-response.md index 15c011ba..ec1d63ec 100644 --- a/doc/models/update-customer-response.md +++ b/doc/models/update-customer-response.md @@ -1,49 +1,49 @@ -## Update Customer Response - -Defines the fields that are included in the response body of -a request to the UpdateCustomer endpoint. - -One of `errors` or `customer` is present in a given response (never both). - -### Structure - -`UpdateCustomerResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `customer` | [`Customer Hash`](/doc/models/customer.md) | Optional | Represents one of a business's customers, which can have one or more
cards on file associated with it. | - -### Example (as JSON) - -```json -{ - "customer": { - "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", - "created_at": "2016-03-23T20:21:54.859Z", - "updated_at": "2016-03-25T20:21:55Z", - "given_name": "Amelia", - "family_name": "Earhart", - "email_address": "New.Amelia.Earhart@example.com", - "address": { - "address_line_1": "500 Electric Ave", - "address_line_2": "Suite 600", - "locality": "New York", - "administrative_district_level_1": "NY", - "postal_code": "10003", - "country": "US" - }, - "reference_id": "YOUR_REFERENCE_ID", - "note": "updated customer note", - "groups": [ - { - "id": "16894e93-96eb-4ced-b24b-f71d42bf084c", - "name": "Aviation Enthusiasts" - } - ] - } -} -``` - +## Update Customer Response + +Defines the fields that are included in the response body of +a request to the UpdateCustomer endpoint. + +One of `errors` or `customer` is present in a given response (never both). + +### Structure + +`UpdateCustomerResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `customer` | [`Customer Hash`](/doc/models/customer.md) | Optional | Represents one of a business's customers, which can have one or more
cards on file associated with it. | + +### Example (as JSON) + +```json +{ + "customer": { + "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", + "created_at": "2016-03-23T20:21:54.859Z", + "updated_at": "2016-03-25T20:21:55Z", + "given_name": "Amelia", + "family_name": "Earhart", + "email_address": "New.Amelia.Earhart@example.com", + "address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "locality": "New York", + "administrative_district_level_1": "NY", + "postal_code": "10003", + "country": "US" + }, + "reference_id": "YOUR_REFERENCE_ID", + "note": "updated customer note", + "groups": [ + { + "id": "16894e93-96eb-4ced-b24b-f71d42bf084c", + "name": "Aviation Enthusiasts" + } + ] + } +} +``` + diff --git a/doc/models/update-item-modifier-lists-request.md b/doc/models/update-item-modifier-lists-request.md index d783e49e..031559c6 100644 --- a/doc/models/update-item-modifier-lists-request.md +++ b/doc/models/update-item-modifier-lists-request.md @@ -1,32 +1,32 @@ -## Update Item Modifier Lists Request - -### Structure - -`UpdateItemModifierListsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `item_ids` | `Array` | | The [CatalogItem](./models/catalog-item.md)s whose [CatalogModifierList](./models/catalog-modifier-list.md)s are being updated. | -| `modifier_lists_to_enable` | `Array` | Optional | The set of [CatalogModifierList](./models/catalog-modifier-list.md)s (referenced by ID) to enable for the [CatalogItem](./models/catalog-item.md). | -| `modifier_lists_to_disable` | `Array` | Optional | The set of [CatalogModifierList](./models/catalog-modifier-list.md)s (referenced by ID) to disable for the [CatalogItem](./models/catalog-item.md). | - -### Example (as JSON) - -```json -{ - "item_ids": [ - "H42BRLUJ5KTZTTMPVSLFAACQ", - "2JXOBJIHCWBQ4NZ3RIXQGJA6" - ], - "modifier_lists_to_enable": [ - "H42BRLUJ5KTZTTMPVSLFAACQ", - "2JXOBJIHCWBQ4NZ3RIXQGJA6" - ], - "modifier_lists_to_disable": [ - "7WRC16CJZDVLSNDQ35PP6YAD" - ] -} -``` - +## Update Item Modifier Lists Request + +### Structure + +`UpdateItemModifierListsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `item_ids` | `Array` | | The [CatalogItem](#type-catalogitem)s whose [CatalogModifierList](#type-catalogmodifierlist)s are being updated. | +| `modifier_lists_to_enable` | `Array` | Optional | The set of [CatalogModifierList](#type-catalogmodifierlist)s (referenced by ID) to enable for the [CatalogItem](#type-catalogitem). | +| `modifier_lists_to_disable` | `Array` | Optional | The set of [CatalogModifierList](#type-catalogmodifierlist)s (referenced by ID) to disable for the [CatalogItem](#type-catalogitem). | + +### Example (as JSON) + +```json +{ + "item_ids": [ + "H42BRLUJ5KTZTTMPVSLFAACQ", + "2JXOBJIHCWBQ4NZ3RIXQGJA6" + ], + "modifier_lists_to_enable": [ + "H42BRLUJ5KTZTTMPVSLFAACQ", + "2JXOBJIHCWBQ4NZ3RIXQGJA6" + ], + "modifier_lists_to_disable": [ + "7WRC16CJZDVLSNDQ35PP6YAD" + ] +} +``` + diff --git a/doc/models/update-item-modifier-lists-response.md b/doc/models/update-item-modifier-lists-response.md index 7f43717c..63d5997d 100644 --- a/doc/models/update-item-modifier-lists-response.md +++ b/doc/models/update-item-modifier-lists-response.md @@ -1,21 +1,21 @@ -## Update Item Modifier Lists Response - -### Structure - -`UpdateItemModifierListsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `updated_at` | `String` | Optional | The database [timestamp](#workingwithdates) of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | - -### Example (as JSON) - -```json -{ - "updated_at": "2016-11-16T22:25:24.878Z" -} -``` - +## Update Item Modifier Lists Response + +### Structure + +`UpdateItemModifierListsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `updated_at` | `String` | Optional | The database [timestamp](#workingwithdates) of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | + +### Example (as JSON) + +```json +{ + "updated_at": "2016-11-16T22:25:24.878Z" +} +``` + diff --git a/doc/models/update-item-taxes-request.md b/doc/models/update-item-taxes-request.md index ceac1c15..b26a146c 100644 --- a/doc/models/update-item-taxes-request.md +++ b/doc/models/update-item-taxes-request.md @@ -1,31 +1,31 @@ -## Update Item Taxes Request - -### Structure - -`UpdateItemTaxesRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `item_ids` | `Array` | | The [CatalogItem](./models/catalog-item.md)s whose enabled/disabled [CatalogTax](./models/catalog-tax.md)es are being updated. | -| `taxes_to_enable` | `Array` | Optional | The set of [CatalogTax](./models/catalog-tax.md)es (referenced by ID) to enable for the [CatalogItem](./models/catalog-item.md). | -| `taxes_to_disable` | `Array` | Optional | The set of [CatalogTax](./models/catalog-tax.md)es (referenced by ID) to disable for the [CatalogItem](./models/catalog-item.md). | - -### Example (as JSON) - -```json -{ - "item_ids": [ - "H42BRLUJ5KTZTTMPVSLFAACQ", - "2JXOBJIHCWBQ4NZ3RIXQGJA6" - ], - "taxes_to_enable": [ - "4WRCNHCJZDVLSNDQ35PP6YAD" - ], - "taxes_to_disable": [ - "AQCEGCEBBQONINDOHRGZISEX" - ] -} -``` - +## Update Item Taxes Request + +### Structure + +`UpdateItemTaxesRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `item_ids` | `Array` | | The [CatalogItem](#type-catalogitem)s whose enabled/disabled [CatalogTax](#type-catalogtax)es are being updated. | +| `taxes_to_enable` | `Array` | Optional | The set of [CatalogTax](#type-catalogtax)es (referenced by ID) to enable for the [CatalogItem](#type-catalogitem). | +| `taxes_to_disable` | `Array` | Optional | The set of [CatalogTax](#type-catalogtax)es (referenced by ID) to disable for the [CatalogItem](#type-catalogitem). | + +### Example (as JSON) + +```json +{ + "item_ids": [ + "H42BRLUJ5KTZTTMPVSLFAACQ", + "2JXOBJIHCWBQ4NZ3RIXQGJA6" + ], + "taxes_to_enable": [ + "4WRCNHCJZDVLSNDQ35PP6YAD" + ], + "taxes_to_disable": [ + "AQCEGCEBBQONINDOHRGZISEX" + ] +} +``` + diff --git a/doc/models/update-item-taxes-response.md b/doc/models/update-item-taxes-response.md index 6694cb42..3c236823 100644 --- a/doc/models/update-item-taxes-response.md +++ b/doc/models/update-item-taxes-response.md @@ -1,21 +1,21 @@ -## Update Item Taxes Response - -### Structure - -`UpdateItemTaxesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `updated_at` | `String` | Optional | The database [timestamp](#workingwithdates) of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | - -### Example (as JSON) - -```json -{ - "updated_at": "2016-11-16T22:25:24.878Z" -} -``` - +## Update Item Taxes Response + +### Structure + +`UpdateItemTaxesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `updated_at` | `String` | Optional | The database [timestamp](#workingwithdates) of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". | + +### Example (as JSON) + +```json +{ + "updated_at": "2016-11-16T22:25:24.878Z" +} +``` + diff --git a/doc/models/update-location-request.md b/doc/models/update-location-request.md new file mode 100644 index 00000000..e9796850 --- /dev/null +++ b/doc/models/update-location-request.md @@ -0,0 +1,22 @@ +## Update Location Request + +Request object for the [UpdateLocation](#endpoint-updatelocation) endpoint. + +### Structure + +`UpdateLocationRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location` | [`Location Hash`](/doc/models/location.md) | Optional | Represents one of a business's locations. | + +### Example (as JSON) + +```json +{ + "location": null +} +``` + diff --git a/doc/models/update-location-response.md b/doc/models/update-location-response.md new file mode 100644 index 00000000..0909613f --- /dev/null +++ b/doc/models/update-location-response.md @@ -0,0 +1,24 @@ +## Update Location Response + +Response object returned by the [UpdateLocation](#endpoint-updatelocation) endpoint. + +### Structure + +`UpdateLocationResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `location` | [`Location Hash`](/doc/models/location.md) | Optional | Represents one of a business's locations. | + +### Example (as JSON) + +```json +{ + "errors": null, + "location": null +} +``` + diff --git a/doc/models/update-order-request.md b/doc/models/update-order-request.md index 8c698256..fe3af72c 100644 --- a/doc/models/update-order-request.md +++ b/doc/models/update-order-request.md @@ -1,27 +1,27 @@ -## Update Order Request - -Defines the fields that are included in requests to the -[UpdateOrder](/doc/orders.md#updateorder) endpoint. - -### Structure - -`UpdateOrderRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | -| `fields_to_clear` | `Array` | Optional | The paths of fields within the order to clear. For example, `line_items[uid].note` | -| `idempotency_key` | `String` | Optional | A value you specify that uniquely identities this update request

If you're unsure whether a particular update was applied to an order successfully,
you can reattempt it with the same idempotency key without
worrying about creating duplicate updates to the order.
The latest order version will be returned.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | - -### Example (as JSON) - -```json -{ - "order": null, - "fields_to_clear": null, - "idempotency_key": null -} -``` - +## Update Order Request + +Defines the fields that are included in requests to the +[UpdateOrder](#endpoint-orders-updateorder) endpoint. + +### Structure + +`UpdateOrderRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | +| `fields_to_clear` | `Array` | Optional | The [dot notation paths](https://developer.squareup.com/docs/orders-api/manage-orders#on-dot-notation)
fields to clear. For example, `line_items[uid].note`
[Read more about Deleting fields](https://developer.squareup.com/docs/orders-api/manage-orders#delete-fields). | +| `idempotency_key` | `String` | Optional | A value you specify that uniquely identifies this update request

If you're unsure whether a particular update was applied to an order successfully,
you can reattempt it with the same idempotency key without
worrying about creating duplicate updates to the order.
The latest order version will be returned.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | + +### Example (as JSON) + +```json +{ + "order": null, + "fields_to_clear": null, + "idempotency_key": null +} +``` + diff --git a/doc/models/update-order-response.md b/doc/models/update-order-response.md index 7225ec64..646d7bf2 100644 --- a/doc/models/update-order-response.md +++ b/doc/models/update-order-response.md @@ -1,25 +1,128 @@ -## Update Order Response - -Defines the fields that are included in the response body of -a request to the [UpdateOrder](/doc/orders.md#updateorder) endpoint. - -### Structure - -`UpdateOrderResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "order": null, - "errors": null -} -``` - +## Update Order Response + +Defines the fields that are included in the response body of +a request to the [UpdateOrder](#endpoint-orders-updateorder) endpoint. + +### Structure + +`UpdateOrderResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`Order Hash`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order objects also
include information on any associated tenders, refunds, and returns.

All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "order": { + "version": 2, + "total_money": { + "currency": "USD", + "amount": 900 + }, + "source": { + "name": "Cookies" + }, + "line_items": [ + { + "total_tax_money": { + "currency": "USD", + "amount": 0 + }, + "total_money": { + "amount": 500, + "currency": "USD" + }, + "gross_sales_money": { + "amount": 500, + "currency": "USD" + }, + "base_price_money": { + "amount": 500, + "currency": "USD" + }, + "quantity": "1", + "total_discount_money": { + "currency": "USD", + "amount": 0 + }, + "name": "Small Coffee", + "uid": "EuYkakhmu3ksHIds5Hiot", + "variation_total_price_money": { + "amount": 500, + "currency": "USD" + } + }, + { + "total_money": { + "amount": 400, + "currency": "USD" + }, + "gross_sales_money": { + "currency": "USD", + "amount": 400 + }, + "total_tax_money": { + "currency": "USD", + "amount": 0 + }, + "variation_total_price_money": { + "currency": "USD", + "amount": 400 + }, + "name": "COOKIE", + "uid": "cookie_uid", + "base_price_money": { + "amount": 200, + "currency": "USD" + }, + "quantity": "2", + "total_discount_money": { + "amount": 0, + "currency": "USD" + } + } + ], + "state": "OPEN", + "total_service_charge_money": { + "amount": 0, + "currency": "USD" + }, + "id": "DREk7wJcyXNHqULq8JJ2iPAsluJZY", + "location_id": "MXVQSVNDGN3C8", + "total_tax_money": { + "amount": 0, + "currency": "USD" + }, + "created_at": "2019-08-23T18:26:18.243Z", + "total_discount_money": { + "amount": 0, + "currency": "USD" + }, + "net_amounts": { + "service_charge_money": { + "currency": "USD", + "amount": 0 + }, + "total_money": { + "amount": 900, + "currency": "USD" + }, + "discount_money": { + "currency": "USD", + "amount": 0 + }, + "tax_money": { + "currency": "USD", + "amount": 0 + } + }, + "updated_at": "2019-08-23T18:33:47.523Z" + } +} +``` + diff --git a/doc/models/update-shift-request.md b/doc/models/update-shift-request.md index 6c67db06..9efe9c47 100644 --- a/doc/models/update-shift-request.md +++ b/doc/models/update-shift-request.md @@ -1,46 +1,46 @@ -## Update Shift Request - -A request to update a `Shift` object. - -### Structure - -`UpdateShiftRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `shift` | [`Shift Hash`](/doc/models/shift.md) | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. | - -### Example (as JSON) - -```json -{ - "shift": { - "employee_id": "ormj0jJJZ5OZIzxrZYJI", - "location_id": "PAA1RJZZKXBFG", - "start_at": "2019-01-25T03:11:00-05:00", - "end_at": "2019-01-25T13:11:00-05:00", - "wage": { - "title": "Bartender", - "hourly_rate": { - "amount": 1500, - "currency": "USD" - } - }, - "breaks": [ - { - "id": "X7GAQYVVRRG6P", - "start_at": "2019-01-25T06:11:00-05:00", - "end_at": "2019-01-25T06:16:00-05:00", - "break_type_id": "REGS1EQR1TPZ5", - "name": "Tea Break", - "expected_duration": "PT5M", - "is_paid": true - } - ], - "version": 1 - } -} -``` - +## Update Shift Request + +A request to update a `Shift` object. + +### Structure + +`UpdateShiftRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `shift` | [`Shift Hash`](/doc/models/shift.md) | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. | + +### Example (as JSON) + +```json +{ + "shift": { + "employee_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-25T03:11:00-05:00", + "end_at": "2019-01-25T13:11:00-05:00", + "wage": { + "title": "Bartender", + "hourly_rate": { + "amount": 1500, + "currency": "USD" + } + }, + "breaks": [ + { + "id": "X7GAQYVVRRG6P", + "start_at": "2019-01-25T06:11:00-05:00", + "end_at": "2019-01-25T06:16:00-05:00", + "break_type_id": "REGS1EQR1TPZ5", + "name": "Tea Break", + "expected_duration": "PT5M", + "is_paid": true + } + ], + "version": 1 + } +} +``` + diff --git a/doc/models/update-shift-response.md b/doc/models/update-shift-response.md index 7fc8bca7..4503b9b2 100644 --- a/doc/models/update-shift-response.md +++ b/doc/models/update-shift-response.md @@ -1,54 +1,54 @@ -## Update Shift Response - -The response to a request to update a `Shift`. Contains -the updated `Shift` object. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`UpdateShiftResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `shift` | [`Shift Hash`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "shift": { - "id": "K0YH4CV5462JB", - "employee_id": "ormj0jJJZ5OZIzxrZYJI", - "location_id": "PAA1RJZZKXBFG", - "timezone": "America/New_York", - "start_at": "2019-01-25T03:11:00-05:00", - "end_at": "2019-01-25T13:11:00-05:00", - "wage": { - "title": "Bartender", - "hourly_rate": { - "amount": 1500, - "currency": "USD" - } - }, - "breaks": [ - { - "id": "X7GAQYVVRRG6P", - "start_at": "2019-01-25T06:11:00-05:00", - "end_at": "2019-01-25T06:16:00-05:00", - "break_type_id": "REGS1EQR1TPZ5", - "name": "Tea Break", - "expected_duration": "PT5M", - "is_paid": true - } - ], - "status": "CLOSED", - "version": 2, - "created_at": "2019-02-28T00:39:02Z", - "updated_at": "2019-02-28T00:42:41Z" - } -} -``` - +## Update Shift Response + +The response to a request to update a `Shift`. Contains +the updated `Shift` object. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`UpdateShiftResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `shift` | [`Shift Hash`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "shift": { + "id": "K0YH4CV5462JB", + "employee_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "timezone": "America/New_York", + "start_at": "2019-01-25T03:11:00-05:00", + "end_at": "2019-01-25T13:11:00-05:00", + "wage": { + "title": "Bartender", + "hourly_rate": { + "amount": 1500, + "currency": "USD" + } + }, + "breaks": [ + { + "id": "X7GAQYVVRRG6P", + "start_at": "2019-01-25T06:11:00-05:00", + "end_at": "2019-01-25T06:16:00-05:00", + "break_type_id": "REGS1EQR1TPZ5", + "name": "Tea Break", + "expected_duration": "PT5M", + "is_paid": true + } + ], + "status": "CLOSED", + "version": 2, + "created_at": "2019-02-28T00:39:02Z", + "updated_at": "2019-02-28T00:42:41Z" + } +} +``` + diff --git a/doc/models/update-workweek-config-request.md b/doc/models/update-workweek-config-request.md index f3cb12fe..0d3ad1d8 100644 --- a/doc/models/update-workweek-config-request.md +++ b/doc/models/update-workweek-config-request.md @@ -1,26 +1,26 @@ -## Update Workweek Config Request - -A request to update a `WorkweekConfig` object - -### Structure - -`UpdateWorkweekConfigRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `workweek_config` | [`Workweek Config Hash`](/doc/models/workweek-config.md) | Optional | Sets the Day of the week and hour of the day that a business starts a
work week. Used for the calculation of overtime pay. | - -### Example (as JSON) - -```json -{ - "workweek_config": { - "start_of_week": "MON", - "start_of_day_local_time": "10:00", - "version": 10 - } -} -``` - +## Update Workweek Config Request + +A request to update a `WorkweekConfig` object + +### Structure + +`UpdateWorkweekConfigRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `workweek_config` | [`Workweek Config Hash`](/doc/models/workweek-config.md) | Optional | Sets the Day of the week and hour of the day that a business starts a
work week. Used for the calculation of overtime pay. | + +### Example (as JSON) + +```json +{ + "workweek_config": { + "start_of_week": "MON", + "start_of_day_local_time": "10:00", + "version": 10 + } +} +``` + diff --git a/doc/models/update-workweek-config-response.md b/doc/models/update-workweek-config-response.md index b965cdd3..beedb31d 100644 --- a/doc/models/update-workweek-config-response.md +++ b/doc/models/update-workweek-config-response.md @@ -1,32 +1,32 @@ -## Update Workweek Config Response - -The response to a request to update a `WorkweekConfig` object. Contains -the updated `WorkweekConfig` object. May contain a set of `Error` objects if -the request resulted in errors. - -### Structure - -`UpdateWorkweekConfigResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `workweek_config` | [`Workweek Config Hash`](/doc/models/workweek-config.md) | Optional | Sets the Day of the week and hour of the day that a business starts a
work week. Used for the calculation of overtime pay. | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{ - "workweek_config": { - "id": "FY4VCAQN700GM", - "start_of_week": "MON", - "start_of_day_local_time": "10:00", - "version": 11, - "created_at": "2016-02-04T00:58:24Z", - "updated_at": "2019-02-28T01:04:35Z" - } -} -``` - +## Update Workweek Config Response + +The response to a request to update a `WorkweekConfig` object. Contains +the updated `WorkweekConfig` object. May contain a set of `Error` objects if +the request resulted in errors. + +### Structure + +`UpdateWorkweekConfigResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `workweek_config` | [`Workweek Config Hash`](/doc/models/workweek-config.md) | Optional | Sets the Day of the week and hour of the day that a business starts a
work week. Used for the calculation of overtime pay. | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{ + "workweek_config": { + "id": "FY4VCAQN700GM", + "start_of_week": "MON", + "start_of_day_local_time": "10:00", + "version": 11, + "created_at": "2016-02-04T00:58:24Z", + "updated_at": "2019-02-28T01:04:35Z" + } +} +``` + diff --git a/doc/models/upsert-catalog-object-request.md b/doc/models/upsert-catalog-object-request.md index 1d5da479..8f6b97c6 100644 --- a/doc/models/upsert-catalog-object-request.md +++ b/doc/models/upsert-catalog-object-request.md @@ -1,30 +1,30 @@ -## Upsert Catalog Object Request - -### Structure - -`UpsertCatalogObjectRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `idempotency_key` | `String` | A value you specify that uniquely identifies this
request among all your requests. A common way to create
a valid idempotency key is to use a Universally unique
identifier (UUID).

If you're unsure whether a particular request was successful,
you can reattempt it with the same idempotency key without
worrying about creating duplicate objects.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | -| `object` | [`Catalog Object Hash`](/doc/models/catalog-object.md) | - | - -### Example (as JSON) - -```json -{ - "idempotency_key": "af3d1afc-7212-4300-b463-0bfc5314a5ae", - "object": { - "type": "ITEM", - "id": "#Cocoa", - "item_data": { - "name": "Cocoa", - "description": "Hot chocolate", - "abbreviation": "Ch" - } - } -} -``` - +## Upsert Catalog Object Request + +### Structure + +`UpsertCatalogObjectRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `idempotency_key` | `String` | A value you specify that uniquely identifies this
request among all your requests. A common way to create
a valid idempotency key is to use a Universally unique
identifier (UUID).

If you're unsure whether a particular request was successful,
you can reattempt it with the same idempotency key without
worrying about creating duplicate objects.

See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | +| `object` | [`Catalog Object Hash`](/doc/models/catalog-object.md) | - | + +### Example (as JSON) + +```json +{ + "idempotency_key": "af3d1afc-7212-4300-b463-0bfc5314a5ae", + "object": { + "type": "ITEM", + "id": "#Cocoa", + "item_data": { + "name": "Cocoa", + "description": "Hot chocolate", + "abbreviation": "Ch" + } + } +} +``` + diff --git a/doc/models/upsert-catalog-object-response.md b/doc/models/upsert-catalog-object-response.md index 40d70376..f93e7b04 100644 --- a/doc/models/upsert-catalog-object-response.md +++ b/doc/models/upsert-catalog-object-response.md @@ -1,39 +1,39 @@ -## Upsert Catalog Object Response - -### Structure - -`UpsertCatalogObjectResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](./models/error.md)s encountered. | -| `catalog_object` | [`Catalog Object Hash`](/doc/models/catalog-object.md) | Optional | - | -| `id_mappings` | [`Array`](/doc/models/catalog-id-mapping.md) | Optional | The mapping between client and server IDs for this Upsert. | - -### Example (as JSON) - -```json -{ - "catalog_object": { - "type": "ITEM", - "id": "7SB3ZQYJ5GDMVFL7JK46JCHT", - "updated_at": "2016-11-16T22:32:42.996Z", - "version": 1479335562996, - "is_deleted": false, - "item_data": { - "name": "Cocoa", - "description": "Hot chocolate", - "abbreviation": "Ch" - } - }, - "id_mappings": [ - { - "client_object_id": "#Cocoa", - "object_id": "7SB3ZQYJ5GDMVFL7JK46JCHT" - } - ] -} -``` - +## Upsert Catalog Object Response + +### Structure + +`UpsertCatalogObjectResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | The set of [Error](#type-error)s encountered. | +| `catalog_object` | [`Catalog Object Hash`](/doc/models/catalog-object.md) | Optional | - | +| `id_mappings` | [`Array`](/doc/models/catalog-id-mapping.md) | Optional | The mapping between client and server IDs for this Upsert. | + +### Example (as JSON) + +```json +{ + "catalog_object": { + "type": "ITEM", + "id": "7SB3ZQYJ5GDMVFL7JK46JCHT", + "updated_at": "2016-11-16T22:32:42.996Z", + "version": 1479335562996, + "is_deleted": false, + "item_data": { + "name": "Cocoa", + "description": "Hot chocolate", + "abbreviation": "Ch" + } + }, + "id_mappings": [ + { + "client_object_id": "#Cocoa", + "object_id": "7SB3ZQYJ5GDMVFL7JK46JCHT" + } + ] +} +``` + diff --git a/doc/models/v1-adjust-inventory-request-adjustment-type.md b/doc/models/v1-adjust-inventory-request-adjustment-type.md index 81a79123..52abd749 100644 --- a/doc/models/v1-adjust-inventory-request-adjustment-type.md +++ b/doc/models/v1-adjust-inventory-request-adjustment-type.md @@ -1,14 +1,14 @@ -## V1 Adjust Inventory Request Adjustment Type - -### Enumeration - -`V1AdjustInventoryRequestAdjustmentType` - -### Fields - -| Name | Description | -| --- | --- | -| `SALE` | - | -| `RECEIVE_STOCK` | - | -| `MANUAL_ADJUST` | - | - +## V1 Adjust Inventory Request Adjustment Type + +### Enumeration + +`V1AdjustInventoryRequestAdjustmentType` + +### Fields + +| Name | Description | +| --- | --- | +| `SALE` | - | +| `RECEIVE_STOCK` | - | +| `MANUAL_ADJUST` | - | + diff --git a/doc/models/v1-adjust-inventory-request.md b/doc/models/v1-adjust-inventory-request.md index d83b3482..35eecc5f 100644 --- a/doc/models/v1-adjust-inventory-request.md +++ b/doc/models/v1-adjust-inventory-request.md @@ -1,26 +1,26 @@ -## V1 Adjust Inventory Request - -V1AdjustInventoryRequest - -### Structure - -`V1AdjustInventoryRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `quantity_delta` | `Float` | Optional | The number to adjust the variation's quantity by. | -| `adjustment_type` | [`String (V1 Adjust Inventory Request Adjustment Type)`](/doc/models/v1-adjust-inventory-request-adjustment-type.md) | Optional | - | -| `memo` | `String` | Optional | A note about the inventory adjustment. | - -### Example (as JSON) - -```json -{ - "quantity_delta": null, - "adjustment_type": null, - "memo": null -} -``` - +## V1 Adjust Inventory Request + +V1AdjustInventoryRequest + +### Structure + +`V1AdjustInventoryRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `quantity_delta` | `Float` | Optional | The number to adjust the variation's quantity by. | +| `adjustment_type` | [`String (V1 Adjust Inventory Request Adjustment Type)`](/doc/models/v1-adjust-inventory-request-adjustment-type.md) | Optional | - | +| `memo` | `String` | Optional | A note about the inventory adjustment. | + +### Example (as JSON) + +```json +{ + "quantity_delta": null, + "adjustment_type": null, + "memo": null +} +``` + diff --git a/doc/models/v1-bank-account-type.md b/doc/models/v1-bank-account-type.md index 250b8681..24a55424 100644 --- a/doc/models/v1-bank-account-type.md +++ b/doc/models/v1-bank-account-type.md @@ -1,17 +1,17 @@ -## V1 Bank Account Type - -### Enumeration - -`V1BankAccountType` - -### Fields - -| Name | Description | -| --- | --- | -| `BUSINESS_CHECKING` | - | -| `CHECKING` | - | -| `INVESTMENT` | - | -| `LOAN` | - | -| `SAVINGS` | - | -| `OTHER` | - | - +## V1 Bank Account Type + +### Enumeration + +`V1BankAccountType` + +### Fields + +| Name | Description | +| --- | --- | +| `BUSINESS_CHECKING` | - | +| `CHECKING` | - | +| `INVESTMENT` | - | +| `LOAN` | - | +| `SAVINGS` | - | +| `OTHER` | - | + diff --git a/doc/models/v1-bank-account.md b/doc/models/v1-bank-account.md index ba99df6e..4a3144b1 100644 --- a/doc/models/v1-bank-account.md +++ b/doc/models/v1-bank-account.md @@ -1,36 +1,36 @@ -## V1 Bank Account - -V1BankAccount - -### Structure - -`V1BankAccount` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The bank account's Square-issued ID. | -| `merchant_id` | `String` | Optional | The Square-issued ID of the merchant associated with the bank account. | -| `bank_name` | `String` | Optional | The name of the bank that manages the account. | -| `name` | `String` | Optional | The name associated with the bank account. | -| `routing_number` | `String` | Optional | The bank account's routing number. | -| `account_number_suffix` | `String` | Optional | The last few digits of the bank account number. | -| `currency_code` | `String` | Optional | The currency code of the currency associated with the bank account, in ISO 4217 format. For example, the currency code for US dollars is USD. | -| `type` | [`String (V1 Bank Account Type)`](/doc/models/v1-bank-account-type.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "id": null, - "merchant_id": null, - "bank_name": null, - "name": null, - "routing_number": null, - "account_number_suffix": null, - "currency_code": null, - "type": null -} -``` - +## V1 Bank Account + +V1BankAccount + +### Structure + +`V1BankAccount` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The bank account's Square-issued ID. | +| `merchant_id` | `String` | Optional | The Square-issued ID of the merchant associated with the bank account. | +| `bank_name` | `String` | Optional | The name of the bank that manages the account. | +| `name` | `String` | Optional | The name associated with the bank account. | +| `routing_number` | `String` | Optional | The bank account's routing number. | +| `account_number_suffix` | `String` | Optional | The last few digits of the bank account number. | +| `currency_code` | `String` | Optional | The currency code of the currency associated with the bank account, in ISO 4217 format. For example, the currency code for US dollars is USD. | +| `type` | [`String (V1 Bank Account Type)`](/doc/models/v1-bank-account-type.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "id": null, + "merchant_id": null, + "bank_name": null, + "name": null, + "routing_number": null, + "account_number_suffix": null, + "currency_code": null, + "type": null +} +``` + diff --git a/doc/models/v1-cash-drawer-event-event-type.md b/doc/models/v1-cash-drawer-event-event-type.md index 495b86bc..31e4c8b8 100644 --- a/doc/models/v1-cash-drawer-event-event-type.md +++ b/doc/models/v1-cash-drawer-event-event-type.md @@ -1,20 +1,20 @@ -## V1 Cash Drawer Event Event Type - -### Enumeration - -`V1CashDrawerEventEventType` - -### Fields - -| Name | Description | -| --- | --- | -| `NO_SALE` | - | -| `CASH_TENDER_PAYMENT` | - | -| `OTHER_TENDER_PAYMENT` | - | -| `CASH_TENDER_CANCELED_PAYMENT` | - | -| `OTHER_TENDER_CANCELED_PAYMENT` | - | -| `CASH_TENDER_REFUND` | - | -| `OTHER_TENDER_REFUND` | - | -| `PAID_IN` | - | -| `PAID_OUT` | - | - +## V1 Cash Drawer Event Event Type + +### Enumeration + +`V1CashDrawerEventEventType` + +### Fields + +| Name | Description | +| --- | --- | +| `NO_SALE` | - | +| `CASH_TENDER_PAYMENT` | - | +| `OTHER_TENDER_PAYMENT` | - | +| `CASH_TENDER_CANCELED_PAYMENT` | - | +| `OTHER_TENDER_CANCELED_PAYMENT` | - | +| `CASH_TENDER_REFUND` | - | +| `OTHER_TENDER_REFUND` | - | +| `PAID_IN` | - | +| `PAID_OUT` | - | + diff --git a/doc/models/v1-cash-drawer-event.md b/doc/models/v1-cash-drawer-event.md index 19ad13a1..c2bf9240 100644 --- a/doc/models/v1-cash-drawer-event.md +++ b/doc/models/v1-cash-drawer-event.md @@ -1,32 +1,32 @@ -## V1 Cash Drawer Event - -V1CashDrawerEvent - -### Structure - -`V1CashDrawerEvent` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The event's unique ID. | -| `employee_id` | `String` | Optional | The ID of the employee that created the event. | -| `event_type` | [`String (V1 Cash Drawer Event Event Type)`](/doc/models/v1-cash-drawer-event-event-type.md) | Optional | - | -| `event_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `created_at` | `String` | Optional | The time when the event occurred, in ISO 8601 format. | -| `description` | `String` | Optional | An optional description of the event, entered by the employee that created it. | - -### Example (as JSON) - -```json -{ - "id": null, - "employee_id": null, - "event_type": null, - "event_money": null, - "created_at": null, - "description": null -} -``` - +## V1 Cash Drawer Event + +V1CashDrawerEvent + +### Structure + +`V1CashDrawerEvent` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The event's unique ID. | +| `employee_id` | `String` | Optional | The ID of the employee that created the event. | +| `event_type` | [`String (V1 Cash Drawer Event Event Type)`](/doc/models/v1-cash-drawer-event-event-type.md) | Optional | - | +| `event_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `created_at` | `String` | Optional | The time when the event occurred, in ISO 8601 format. | +| `description` | `String` | Optional | An optional description of the event, entered by the employee that created it. | + +### Example (as JSON) + +```json +{ + "id": null, + "employee_id": null, + "event_type": null, + "event_money": null, + "created_at": null, + "description": null +} +``` + diff --git a/doc/models/v1-cash-drawer-shift-event-type.md b/doc/models/v1-cash-drawer-shift-event-type.md index 6e63d5c0..b4306e25 100644 --- a/doc/models/v1-cash-drawer-shift-event-type.md +++ b/doc/models/v1-cash-drawer-shift-event-type.md @@ -1,14 +1,14 @@ -## V1 Cash Drawer Shift Event Type - -### Enumeration - -`V1CashDrawerShiftEventType` - -### Fields - -| Name | Description | -| --- | --- | -| `OPEN` | - | -| `ENDED` | - | -| `CLOSED` | - | - +## V1 Cash Drawer Shift Event Type + +### Enumeration + +`V1CashDrawerShiftEventType` + +### Fields + +| Name | Description | +| --- | --- | +| `OPEN` | - | +| `ENDED` | - | +| `CLOSED` | - | + diff --git a/doc/models/v1-cash-drawer-shift.md b/doc/models/v1-cash-drawer-shift.md index c3da5475..3c59af85 100644 --- a/doc/models/v1-cash-drawer-shift.md +++ b/doc/models/v1-cash-drawer-shift.md @@ -1,58 +1,58 @@ -## V1 Cash Drawer Shift - -Contains details for a single cash drawer shift. - -### Structure - -`V1CashDrawerShift` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The shift's unique ID. | -| `event_type` | [`String (V1 Cash Drawer Shift Event Type)`](/doc/models/v1-cash-drawer-shift-event-type.md) | Optional | - | -| `opened_at` | `String` | Optional | The time when the shift began, in ISO 8601 format. | -| `ended_at` | `String` | Optional | The time when the shift ended, in ISO 8601 format. | -| `closed_at` | `String` | Optional | The time when the shift was closed, in ISO 8601 format. | -| `employee_ids` | `Array` | Optional | The IDs of all employees that were logged into Square Register at some point during the cash drawer shift. | -| `opening_employee_id` | `String` | Optional | The ID of the employee that started the cash drawer shift. | -| `ending_employee_id` | `String` | Optional | The ID of the employee that ended the cash drawer shift. | -| `closing_employee_id` | `String` | Optional | The ID of the employee that closed the cash drawer shift by auditing the cash drawer's contents. | -| `description` | `String` | Optional | A description of the cash drawer shift. | -| `starting_cash_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `cash_payment_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `cash_refunds_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `cash_paid_in_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `cash_paid_out_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `expected_cash_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `closed_cash_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `device` | [`Device Hash`](/doc/models/device.md) | Optional | - | -| `events` | [`Array`](/doc/models/v1-cash-drawer-event.md) | Optional | All of the events (payments, refunds, and so on) that involved the cash drawer during the shift. | - -### Example (as JSON) - -```json -{ - "id": null, - "event_type": null, - "opened_at": null, - "ended_at": null, - "closed_at": null, - "employee_ids": null, - "opening_employee_id": null, - "ending_employee_id": null, - "closing_employee_id": null, - "description": null, - "starting_cash_money": null, - "cash_payment_money": null, - "cash_refunds_money": null, - "cash_paid_in_money": null, - "cash_paid_out_money": null, - "expected_cash_money": null, - "closed_cash_money": null, - "device": null, - "events": null -} -``` - +## V1 Cash Drawer Shift + +Contains details for a single cash drawer shift. + +### Structure + +`V1CashDrawerShift` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The shift's unique ID. | +| `event_type` | [`String (V1 Cash Drawer Shift Event Type)`](/doc/models/v1-cash-drawer-shift-event-type.md) | Optional | - | +| `opened_at` | `String` | Optional | The time when the shift began, in ISO 8601 format. | +| `ended_at` | `String` | Optional | The time when the shift ended, in ISO 8601 format. | +| `closed_at` | `String` | Optional | The time when the shift was closed, in ISO 8601 format. | +| `employee_ids` | `Array` | Optional | The IDs of all employees that were logged into Square Register at some point during the cash drawer shift. | +| `opening_employee_id` | `String` | Optional | The ID of the employee that started the cash drawer shift. | +| `ending_employee_id` | `String` | Optional | The ID of the employee that ended the cash drawer shift. | +| `closing_employee_id` | `String` | Optional | The ID of the employee that closed the cash drawer shift by auditing the cash drawer's contents. | +| `description` | `String` | Optional | A description of the cash drawer shift. | +| `starting_cash_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `cash_payment_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `cash_refunds_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `cash_paid_in_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `cash_paid_out_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `expected_cash_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `closed_cash_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `device` | [`Device Hash`](/doc/models/device.md) | Optional | - | +| `events` | [`Array`](/doc/models/v1-cash-drawer-event.md) | Optional | All of the events (payments, refunds, and so on) that involved the cash drawer during the shift. | + +### Example (as JSON) + +```json +{ + "id": null, + "event_type": null, + "opened_at": null, + "ended_at": null, + "closed_at": null, + "employee_ids": null, + "opening_employee_id": null, + "ending_employee_id": null, + "closing_employee_id": null, + "description": null, + "starting_cash_money": null, + "cash_payment_money": null, + "cash_refunds_money": null, + "cash_paid_in_money": null, + "cash_paid_out_money": null, + "expected_cash_money": null, + "closed_cash_money": null, + "device": null, + "events": null +} +``` + diff --git a/doc/models/v1-category.md b/doc/models/v1-category.md index f9d68e23..89582aaf 100644 --- a/doc/models/v1-category.md +++ b/doc/models/v1-category.md @@ -1,26 +1,26 @@ -## V1 Category - -V1Category - -### Structure - -`V1Category` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The category's unique ID. | -| `name` | `String` | Optional | The category's name. | -| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null, - "v2_id": null -} -``` - +## V1 Category + +V1Category + +### Structure + +`V1Category` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The category's unique ID. | +| `name` | `String` | Optional | The category's name. | +| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null, + "v2_id": null +} +``` + diff --git a/doc/models/v1-create-category-request.md b/doc/models/v1-create-category-request.md index d2d26be1..580d589d 100644 --- a/doc/models/v1-create-category-request.md +++ b/doc/models/v1-create-category-request.md @@ -1,20 +1,20 @@ -## V1 Create Category Request - -### Structure - -`V1CreateCategoryRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Category Hash`](/doc/models/v1-category.md) | Optional | V1Category | - -### Example (as JSON) - -```json -{ - "body": null -} -``` - +## V1 Create Category Request + +### Structure + +`V1CreateCategoryRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Category Hash`](/doc/models/v1-category.md) | Optional | V1Category | + +### Example (as JSON) + +```json +{ + "body": null +} +``` + diff --git a/doc/models/v1-create-discount-request.md b/doc/models/v1-create-discount-request.md index e4dd9f62..d325ea15 100644 --- a/doc/models/v1-create-discount-request.md +++ b/doc/models/v1-create-discount-request.md @@ -1,20 +1,20 @@ -## V1 Create Discount Request - -### Structure - -`V1CreateDiscountRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Discount Hash`](/doc/models/v1-discount.md) | Optional | V1Discount | - -### Example (as JSON) - -```json -{ - "body": null -} -``` - +## V1 Create Discount Request + +### Structure + +`V1CreateDiscountRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Discount Hash`](/doc/models/v1-discount.md) | Optional | V1Discount | + +### Example (as JSON) + +```json +{ + "body": null +} +``` + diff --git a/doc/models/v1-create-employee-role-request.md b/doc/models/v1-create-employee-role-request.md index e43b8cb6..2479193e 100644 --- a/doc/models/v1-create-employee-role-request.md +++ b/doc/models/v1-create-employee-role-request.md @@ -1,20 +1,20 @@ -## V1 Create Employee Role Request - -### Structure - -`V1CreateEmployeeRoleRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `employee_role` | [`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) | Optional | V1EmployeeRole | - -### Example (as JSON) - -```json -{ - "employee_role": null -} -``` - +## V1 Create Employee Role Request + +### Structure + +`V1CreateEmployeeRoleRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `employee_role` | [`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) | Optional | V1EmployeeRole | + +### Example (as JSON) + +```json +{ + "employee_role": null +} +``` + diff --git a/doc/models/v1-create-fee-request.md b/doc/models/v1-create-fee-request.md index 6f6477f3..2ad5526c 100644 --- a/doc/models/v1-create-fee-request.md +++ b/doc/models/v1-create-fee-request.md @@ -1,20 +1,20 @@ -## V1 Create Fee Request - -### Structure - -`V1CreateFeeRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Fee Hash`](/doc/models/v1-fee.md) | Optional | V1Fee | - -### Example (as JSON) - -```json -{ - "body": null -} -``` - +## V1 Create Fee Request + +### Structure + +`V1CreateFeeRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Fee Hash`](/doc/models/v1-fee.md) | Optional | V1Fee | + +### Example (as JSON) + +```json +{ + "body": null +} +``` + diff --git a/doc/models/v1-create-item-request.md b/doc/models/v1-create-item-request.md index 12b0143f..46e7d55f 100644 --- a/doc/models/v1-create-item-request.md +++ b/doc/models/v1-create-item-request.md @@ -1,20 +1,20 @@ -## V1 Create Item Request - -### Structure - -`V1CreateItemRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Item Hash`](/doc/models/v1-item.md) | Optional | V1Item | - -### Example (as JSON) - -```json -{ - "body": null -} -``` - +## V1 Create Item Request + +### Structure + +`V1CreateItemRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Item Hash`](/doc/models/v1-item.md) | Optional | V1Item | + +### Example (as JSON) + +```json +{ + "body": null +} +``` + diff --git a/doc/models/v1-create-modifier-list-request.md b/doc/models/v1-create-modifier-list-request.md index 6dd344a4..32560b22 100644 --- a/doc/models/v1-create-modifier-list-request.md +++ b/doc/models/v1-create-modifier-list-request.md @@ -1,20 +1,20 @@ -## V1 Create Modifier List Request - -### Structure - -`V1CreateModifierListRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) | Optional | V1ModifierList | - -### Example (as JSON) - -```json -{ - "body": null -} -``` - +## V1 Create Modifier List Request + +### Structure + +`V1CreateModifierListRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) | Optional | V1ModifierList | + +### Example (as JSON) + +```json +{ + "body": null +} +``` + diff --git a/doc/models/v1-create-modifier-option-request.md b/doc/models/v1-create-modifier-option-request.md index e5f8148c..8ae1be18 100644 --- a/doc/models/v1-create-modifier-option-request.md +++ b/doc/models/v1-create-modifier-option-request.md @@ -1,20 +1,20 @@ -## V1 Create Modifier Option Request - -### Structure - -`V1CreateModifierOptionRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) | Optional | V1ModifierOption | - -### Example (as JSON) - -```json -{ - "body": null -} -``` - +## V1 Create Modifier Option Request + +### Structure + +`V1CreateModifierOptionRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) | Optional | V1ModifierOption | + +### Example (as JSON) + +```json +{ + "body": null +} +``` + diff --git a/doc/models/v1-create-page-request.md b/doc/models/v1-create-page-request.md index da420ed8..42e17831 100644 --- a/doc/models/v1-create-page-request.md +++ b/doc/models/v1-create-page-request.md @@ -1,20 +1,20 @@ -## V1 Create Page Request - -### Structure - -`V1CreatePageRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Page Hash`](/doc/models/v1-page.md) | Optional | V1Page | - -### Example (as JSON) - -```json -{ - "body": null -} -``` - +## V1 Create Page Request + +### Structure + +`V1CreatePageRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Page Hash`](/doc/models/v1-page.md) | Optional | V1Page | + +### Example (as JSON) + +```json +{ + "body": null +} +``` + diff --git a/doc/models/v1-create-refund-request-type.md b/doc/models/v1-create-refund-request-type.md index 58816506..b17bfce7 100644 --- a/doc/models/v1-create-refund-request-type.md +++ b/doc/models/v1-create-refund-request-type.md @@ -1,13 +1,13 @@ -## V1 Create Refund Request Type - -### Enumeration - -`V1CreateRefundRequestType` - -### Fields - -| Name | Description | -| --- | --- | -| `FULL` | - | -| `PARTIAL` | - | - +## V1 Create Refund Request Type + +### Enumeration + +`V1CreateRefundRequestType` + +### Fields + +| Name | Description | +| --- | --- | +| `FULL` | - | +| `PARTIAL` | - | + diff --git a/doc/models/v1-create-refund-request.md b/doc/models/v1-create-refund-request.md index 1995fcd9..23af1b33 100644 --- a/doc/models/v1-create-refund-request.md +++ b/doc/models/v1-create-refund-request.md @@ -1,30 +1,30 @@ -## V1 Create Refund Request - -V1CreateRefundRequest - -### Structure - -`V1CreateRefundRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `payment_id` | `String` | | The ID of the payment to refund. If you are creating a `PARTIAL`
refund for a split tender payment, instead provide the id of the
particular tender you want to refund. | -| `type` | [`String (V1 Create Refund Request Type)`](/doc/models/v1-create-refund-request-type.md) | | - | -| `reason` | `String` | | The reason for the refund. | -| `refunded_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `request_idempotence_key` | `String` | Optional | An optional key to ensure idempotence if you issue the same PARTIAL refund request more than once. | - -### Example (as JSON) - -```json -{ - "payment_id": "payment_id0", - "type": "FULL", - "reason": "reason4", - "refunded_money": null, - "request_idempotence_key": null -} -``` - +## V1 Create Refund Request + +V1CreateRefundRequest + +### Structure + +`V1CreateRefundRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `payment_id` | `String` | | The ID of the payment to refund. If you are creating a `PARTIAL`
refund for a split tender payment, instead provide the id of the
particular tender you want to refund. | +| `type` | [`String (V1 Create Refund Request Type)`](/doc/models/v1-create-refund-request-type.md) | | - | +| `reason` | `String` | | The reason for the refund. | +| `refunded_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `request_idempotence_key` | `String` | Optional | An optional key to ensure idempotence if you issue the same PARTIAL refund request more than once. | + +### Example (as JSON) + +```json +{ + "payment_id": "payment_id0", + "type": "FULL", + "reason": "reason4", + "refunded_money": null, + "request_idempotence_key": null +} +``` + diff --git a/doc/models/v1-create-variation-request.md b/doc/models/v1-create-variation-request.md index 07928d1f..a0e0d629 100644 --- a/doc/models/v1-create-variation-request.md +++ b/doc/models/v1-create-variation-request.md @@ -1,20 +1,20 @@ -## V1 Create Variation Request - -### Structure - -`V1CreateVariationRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Variation Hash`](/doc/models/v1-variation.md) | Optional | V1Variation | - -### Example (as JSON) - -```json -{ - "body": null -} -``` - +## V1 Create Variation Request + +### Structure + +`V1CreateVariationRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Variation Hash`](/doc/models/v1-variation.md) | Optional | V1Variation | + +### Example (as JSON) + +```json +{ + "body": null +} +``` + diff --git a/doc/models/v1-delete-page-cell-request.md b/doc/models/v1-delete-page-cell-request.md index 78ed088e..65b4a4ae 100644 --- a/doc/models/v1-delete-page-cell-request.md +++ b/doc/models/v1-delete-page-cell-request.md @@ -1,22 +1,22 @@ -## V1 Delete Page Cell Request - -### Structure - -`V1DeletePageCellRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `row` | `String` | Optional | The row of the cell to clear. Always an integer between 0 and 4, inclusive. Row 0 is the top row. | -| `column` | `String` | Optional | The column of the cell to clear. Always an integer between 0 and 4, inclusive. Column 0 is the leftmost column. | - -### Example (as JSON) - -```json -{ - "row": null, - "column": null -} -``` - +## V1 Delete Page Cell Request + +### Structure + +`V1DeletePageCellRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `row` | `String` | Optional | The row of the cell to clear. Always an integer between 0 and 4, inclusive. Row 0 is the top row. | +| `column` | `String` | Optional | The column of the cell to clear. Always an integer between 0 and 4, inclusive. Column 0 is the leftmost column. | + +### Example (as JSON) + +```json +{ + "row": null, + "column": null +} +``` + diff --git a/doc/models/v1-discount-color.md b/doc/models/v1-discount-color.md index 36330925..1f497896 100644 --- a/doc/models/v1-discount-color.md +++ b/doc/models/v1-discount-color.md @@ -1,20 +1,20 @@ -## V1 Discount Color - -### Enumeration - -`V1DiscountColor` - -### Fields - -| Name | Description | -| --- | --- | -| `Enum_9da2a6` | - | -| `Enum_4ab200` | - | -| `Enum_0b8000` | - | -| `Enum_2952cc` | - | -| `a82ee5` | - | -| `e5457a` | - | -| `b21212` | - | -| `Enum_593c00` | - | -| `e5BF00` | - | - +## V1 Discount Color + +### Enumeration + +`V1DiscountColor` + +### Fields + +| Name | Description | +| --- | --- | +| `Enum_9da2a6` | - | +| `Enum_4ab200` | - | +| `Enum_0b8000` | - | +| `Enum_2952cc` | - | +| `a82ee5` | - | +| `e5457a` | - | +| `b21212` | - | +| `Enum_593c00` | - | +| `e5BF00` | - | + diff --git a/doc/models/v1-discount-discount-type.md b/doc/models/v1-discount-discount-type.md index f15979ea..d167ef53 100644 --- a/doc/models/v1-discount-discount-type.md +++ b/doc/models/v1-discount-discount-type.md @@ -1,14 +1,14 @@ -## V1 Discount Discount Type - -### Enumeration - -`V1DiscountDiscountType` - -### Fields - -| Name | Description | -| --- | --- | -| `FIXED` | - | -| `VARIABLE_PERCENTAGE` | - | -| `VARIABLE_AMOUNT` | - | - +## V1 Discount Discount Type + +### Enumeration + +`V1DiscountDiscountType` + +### Fields + +| Name | Description | +| --- | --- | +| `FIXED` | - | +| `VARIABLE_PERCENTAGE` | - | +| `VARIABLE_AMOUNT` | - | + diff --git a/doc/models/v1-discount.md b/doc/models/v1-discount.md index d81347bd..8e9ab9dc 100644 --- a/doc/models/v1-discount.md +++ b/doc/models/v1-discount.md @@ -1,36 +1,36 @@ -## V1 Discount - -V1Discount - -### Structure - -`V1Discount` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The discount's unique ID. | -| `name` | `String` | Optional | The discount's name. | -| `rate` | `String` | Optional | The rate of the discount, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%. This rate is 0 if discount_type is VARIABLE_PERCENTAGE. | -| `amount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `discount_type` | [`String (V1 Discount Discount Type)`](/doc/models/v1-discount-discount-type.md) | Optional | - | -| `pin_required` | `Boolean` | Optional | Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment. | -| `color` | [`String (V1 Discount Color)`](/doc/models/v1-discount-color.md) | Optional | - | -| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null, - "rate": null, - "amount_money": null, - "discount_type": null, - "pin_required": null, - "color": null, - "v2_id": null -} -``` - +## V1 Discount + +V1Discount + +### Structure + +`V1Discount` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The discount's unique ID. | +| `name` | `String` | Optional | The discount's name. | +| `rate` | `String` | Optional | The rate of the discount, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%. This rate is 0 if discount_type is VARIABLE_PERCENTAGE. | +| `amount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `discount_type` | [`String (V1 Discount Discount Type)`](/doc/models/v1-discount-discount-type.md) | Optional | - | +| `pin_required` | `Boolean` | Optional | Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment. | +| `color` | [`String (V1 Discount Color)`](/doc/models/v1-discount-color.md) | Optional | - | +| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null, + "rate": null, + "amount_money": null, + "discount_type": null, + "pin_required": null, + "color": null, + "v2_id": null +} +``` + diff --git a/doc/models/v1-employee-role-permissions.md b/doc/models/v1-employee-role-permissions.md index 961b5b6c..27e77a98 100644 --- a/doc/models/v1-employee-role-permissions.md +++ b/doc/models/v1-employee-role-permissions.md @@ -1,18 +1,18 @@ -## V1 Employee Role Permissions - -### Enumeration - -`V1EmployeeRolePermissions` - -### Fields - -| Name | Description | -| --- | --- | -| `REGISTER_ACCESS_SALES_HISTORY` | - | -| `REGISTER_APPLY_RESTRICTED_DISCOUNTS` | - | -| `REGISTER_CHANGE_SETTINGS` | - | -| `REGISTER_EDIT_ITEM` | - | -| `REGISTER_ISSUE_REFUNDS` | - | -| `REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE` | - | -| `REGISTER_VIEW_SUMMARY_REPORTS` | - | - +## V1 Employee Role Permissions + +### Enumeration + +`V1EmployeeRolePermissions` + +### Fields + +| Name | Description | +| --- | --- | +| `REGISTER_ACCESS_SALES_HISTORY` | - | +| `REGISTER_APPLY_RESTRICTED_DISCOUNTS` | - | +| `REGISTER_CHANGE_SETTINGS` | - | +| `REGISTER_EDIT_ITEM` | - | +| `REGISTER_ISSUE_REFUNDS` | - | +| `REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE` | - | +| `REGISTER_VIEW_SUMMARY_REPORTS` | - | + diff --git a/doc/models/v1-employee-role.md b/doc/models/v1-employee-role.md index 52409d49..b4e7a120 100644 --- a/doc/models/v1-employee-role.md +++ b/doc/models/v1-employee-role.md @@ -1,35 +1,35 @@ -## V1 Employee Role - -V1EmployeeRole - -### Structure - -`V1EmployeeRole` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The role's unique ID, Can only be set by Square. | -| `name` | `String` | | The role's merchant-defined name. | -| `permissions` | [`Array`](/doc/models/v1-employee-role-permissions.md) | | The role's permissions.
See [V1EmployeeRolePermissions](#type-v1employeerolepermissions) for possible values | -| `is_owner` | `Boolean` | Optional | If true, employees with this role have all permissions, regardless of the values indicated in permissions. | -| `created_at` | `String` | Optional | The time when the employee entity was created, in ISO 8601 format. Is set by Square when the Role is created. | -| `updated_at` | `String` | Optional | The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": "name0", - "permissions": [ - "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE", - "REGISTER_VIEW_SUMMARY_REPORTS" - ], - "is_owner": null, - "created_at": null, - "updated_at": null -} -``` - +## V1 Employee Role + +V1EmployeeRole + +### Structure + +`V1EmployeeRole` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The role's unique ID, Can only be set by Square. | +| `name` | `String` | | The role's merchant-defined name. | +| `permissions` | [`Array`](/doc/models/v1-employee-role-permissions.md) | | The role's permissions.
See [V1EmployeeRolePermissions](#type-v1employeerolepermissions) for possible values | +| `is_owner` | `Boolean` | Optional | If true, employees with this role have all permissions, regardless of the values indicated in permissions. | +| `created_at` | `String` | Optional | The time when the employee entity was created, in ISO 8601 format. Is set by Square when the Role is created. | +| `updated_at` | `String` | Optional | The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": "name0", + "permissions": [ + "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE", + "REGISTER_VIEW_SUMMARY_REPORTS" + ], + "is_owner": null, + "created_at": null, + "updated_at": null +} +``` + diff --git a/doc/models/v1-employee-status.md b/doc/models/v1-employee-status.md index 6948b8f6..a9724c6b 100644 --- a/doc/models/v1-employee-status.md +++ b/doc/models/v1-employee-status.md @@ -1,13 +1,13 @@ -## V1 Employee Status - -### Enumeration - -`V1EmployeeStatus` - -### Fields - -| Name | Description | -| --- | --- | -| `ACTIVE` | - | -| `INACTIVE` | - | - +## V1 Employee Status + +### Enumeration + +`V1EmployeeStatus` + +### Fields + +| Name | Description | +| --- | --- | +| `ACTIVE` | - | +| `INACTIVE` | - | + diff --git a/doc/models/v1-employee.md b/doc/models/v1-employee.md index 40126d7e..fa534f84 100644 --- a/doc/models/v1-employee.md +++ b/doc/models/v1-employee.md @@ -1,40 +1,40 @@ -## V1 Employee - -Represents one of a business's employees. - -### Structure - -`V1Employee` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The employee's unique ID. | -| `first_name` | `String` | | The employee's first name. | -| `last_name` | `String` | | The employee's last name. | -| `role_ids` | `Array` | Optional | The ids of the employee's associated roles. Currently, you can specify only one or zero roles per employee. | -| `authorized_location_ids` | `Array` | Optional | The IDs of the locations the employee is allowed to clock in at. | -| `email` | `String` | Optional | The employee's email address. | -| `status` | [`String (V1 Employee Status)`](/doc/models/v1-employee-status.md) | Optional | - | -| `external_id` | `String` | Optional | An ID the merchant can set to associate the employee with an entity in another system. | -| `created_at` | `String` | Optional | The time when the employee entity was created, in ISO 8601 format. | -| `updated_at` | `String` | Optional | The time when the employee entity was most recently updated, in ISO 8601 format. | - -### Example (as JSON) - -```json -{ - "id": null, - "first_name": "first_name0", - "last_name": "last_name8", - "role_ids": null, - "authorized_location_ids": null, - "email": null, - "status": null, - "external_id": null, - "created_at": null, - "updated_at": null -} -``` - +## V1 Employee + +Represents one of a business's employees. + +### Structure + +`V1Employee` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The employee's unique ID. | +| `first_name` | `String` | | The employee's first name. | +| `last_name` | `String` | | The employee's last name. | +| `role_ids` | `Array` | Optional | The ids of the employee's associated roles. Currently, you can specify only one or zero roles per employee. | +| `authorized_location_ids` | `Array` | Optional | The IDs of the locations the employee is allowed to clock in at. | +| `email` | `String` | Optional | The employee's email address. | +| `status` | [`String (V1 Employee Status)`](/doc/models/v1-employee-status.md) | Optional | - | +| `external_id` | `String` | Optional | An ID the merchant can set to associate the employee with an entity in another system. | +| `created_at` | `String` | Optional | The time when the employee entity was created, in ISO 8601 format. | +| `updated_at` | `String` | Optional | The time when the employee entity was most recently updated, in ISO 8601 format. | + +### Example (as JSON) + +```json +{ + "id": null, + "first_name": "first_name0", + "last_name": "last_name8", + "role_ids": null, + "authorized_location_ids": null, + "email": null, + "status": null, + "external_id": null, + "created_at": null, + "updated_at": null +} +``` + diff --git a/doc/models/v1-fee-adjustment-type.md b/doc/models/v1-fee-adjustment-type.md index 77cf9c26..c9697668 100644 --- a/doc/models/v1-fee-adjustment-type.md +++ b/doc/models/v1-fee-adjustment-type.md @@ -1,12 +1,12 @@ -## V1 Fee Adjustment Type - -### Enumeration - -`V1FeeAdjustmentType` - -### Fields - -| Name | Description | -| --- | --- | -| `TAX` | - | - +## V1 Fee Adjustment Type + +### Enumeration + +`V1FeeAdjustmentType` + +### Fields + +| Name | Description | +| --- | --- | +| `TAX` | - | + diff --git a/doc/models/v1-fee-calculation-phase.md b/doc/models/v1-fee-calculation-phase.md index 03709d97..2b764f08 100644 --- a/doc/models/v1-fee-calculation-phase.md +++ b/doc/models/v1-fee-calculation-phase.md @@ -1,14 +1,14 @@ -## V1 Fee Calculation Phase - -### Enumeration - -`V1FeeCalculationPhase` - -### Fields - -| Name | Description | -| --- | --- | -| `FEE_SUBTOTAL_PHASE` | - | -| `OTHER` | - | -| `FEE_TOTAL_PHASE` | - | - +## V1 Fee Calculation Phase + +### Enumeration + +`V1FeeCalculationPhase` + +### Fields + +| Name | Description | +| --- | --- | +| `FEE_SUBTOTAL_PHASE` | - | +| `OTHER` | - | +| `FEE_TOTAL_PHASE` | - | + diff --git a/doc/models/v1-fee-inclusion-type.md b/doc/models/v1-fee-inclusion-type.md index 32c17a19..ca2113b9 100644 --- a/doc/models/v1-fee-inclusion-type.md +++ b/doc/models/v1-fee-inclusion-type.md @@ -1,13 +1,13 @@ -## V1 Fee Inclusion Type - -### Enumeration - -`V1FeeInclusionType` - -### Fields - -| Name | Description | -| --- | --- | -| `ADDITIVE` | - | -| `INCLUSIVE` | - | - +## V1 Fee Inclusion Type + +### Enumeration + +`V1FeeInclusionType` + +### Fields + +| Name | Description | +| --- | --- | +| `ADDITIVE` | - | +| `INCLUSIVE` | - | + diff --git a/doc/models/v1-fee-type.md b/doc/models/v1-fee-type.md index 9b8ee3a6..a79f83dc 100644 --- a/doc/models/v1-fee-type.md +++ b/doc/models/v1-fee-type.md @@ -1,19 +1,19 @@ -## V1 Fee Type - -### Enumeration - -`V1FeeType` - -### Fields - -| Name | Description | -| --- | --- | -| `CA_GST` | - | -| `CA_HST` | - | -| `CA_PST` | - | -| `CA_QST` | - | -| `JP_CONSUMPTION_TAX` | - | -| `CA_PEI_PST` | - | -| `US_SALES_TAX` | - | -| `OTHER` | - | - +## V1 Fee Type + +### Enumeration + +`V1FeeType` + +### Fields + +| Name | Description | +| --- | --- | +| `CA_GST` | - | +| `CA_HST` | - | +| `CA_PST` | - | +| `CA_QST` | - | +| `JP_CONSUMPTION_TAX` | - | +| `CA_PEI_PST` | - | +| `US_SALES_TAX` | - | +| `OTHER` | - | + diff --git a/doc/models/v1-fee.md b/doc/models/v1-fee.md index 573ea729..a66df1e6 100644 --- a/doc/models/v1-fee.md +++ b/doc/models/v1-fee.md @@ -1,40 +1,40 @@ -## V1 Fee - -V1Fee - -### Structure - -`V1Fee` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The fee's unique ID. | -| `name` | `String` | Optional | The fee's name. | -| `rate` | `String` | Optional | The rate of the fee, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%. | -| `calculation_phase` | [`String (V1 Fee Calculation Phase)`](/doc/models/v1-fee-calculation-phase.md) | Optional | - | -| `adjustment_type` | [`String (V1 Fee Adjustment Type)`](/doc/models/v1-fee-adjustment-type.md) | Optional | - | -| `applies_to_custom_amounts` | `Boolean` | Optional | If true, the fee applies to custom amounts entered into Square Register that are not associated with a particular item. | -| `enabled` | `Boolean` | Optional | If true, the fee is applied to all appropriate items. If false, the fee is not applied at all. | -| `inclusion_type` | [`String (V1 Fee Inclusion Type)`](/doc/models/v1-fee-inclusion-type.md) | Optional | - | -| `type` | [`String (V1 Fee Type)`](/doc/models/v1-fee-type.md) | Optional | - | -| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null, - "rate": null, - "calculation_phase": null, - "adjustment_type": null, - "applies_to_custom_amounts": null, - "enabled": null, - "inclusion_type": null, - "type": null, - "v2_id": null -} -``` - +## V1 Fee + +V1Fee + +### Structure + +`V1Fee` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The fee's unique ID. | +| `name` | `String` | Optional | The fee's name. | +| `rate` | `String` | Optional | The rate of the fee, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%. | +| `calculation_phase` | [`String (V1 Fee Calculation Phase)`](/doc/models/v1-fee-calculation-phase.md) | Optional | - | +| `adjustment_type` | [`String (V1 Fee Adjustment Type)`](/doc/models/v1-fee-adjustment-type.md) | Optional | - | +| `applies_to_custom_amounts` | `Boolean` | Optional | If true, the fee applies to custom amounts entered into Square Register that are not associated with a particular item. | +| `enabled` | `Boolean` | Optional | If true, the fee is applied to all appropriate items. If false, the fee is not applied at all. | +| `inclusion_type` | [`String (V1 Fee Inclusion Type)`](/doc/models/v1-fee-inclusion-type.md) | Optional | - | +| `type` | [`String (V1 Fee Type)`](/doc/models/v1-fee-type.md) | Optional | - | +| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null, + "rate": null, + "calculation_phase": null, + "adjustment_type": null, + "applies_to_custom_amounts": null, + "enabled": null, + "inclusion_type": null, + "type": null, + "v2_id": null +} +``` + diff --git a/doc/models/v1-inventory-entry.md b/doc/models/v1-inventory-entry.md index c4e9fbd8..9aa16c41 100644 --- a/doc/models/v1-inventory-entry.md +++ b/doc/models/v1-inventory-entry.md @@ -1,24 +1,24 @@ -## V1 Inventory Entry - -V1InventoryEntry - -### Structure - -`V1InventoryEntry` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `variation_id` | `String` | Optional | The variation that the entry corresponds to. | -| `quantity_on_hand` | `Float` | Optional | The current available quantity of the item variation. | - -### Example (as JSON) - -```json -{ - "variation_id": null, - "quantity_on_hand": null -} -``` - +## V1 Inventory Entry + +V1InventoryEntry + +### Structure + +`V1InventoryEntry` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `variation_id` | `String` | Optional | The variation that the entry corresponds to. | +| `quantity_on_hand` | `Float` | Optional | The current available quantity of the item variation. | + +### Example (as JSON) + +```json +{ + "variation_id": null, + "quantity_on_hand": null +} +``` + diff --git a/doc/models/v1-item-image.md b/doc/models/v1-item-image.md index 22a0b870..92352acb 100644 --- a/doc/models/v1-item-image.md +++ b/doc/models/v1-item-image.md @@ -1,24 +1,24 @@ -## V1 Item Image - -V1ItemImage - -### Structure - -`V1ItemImage` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The image's unique ID. | -| `url` | `String` | Optional | The image's publicly accessible URL. | - -### Example (as JSON) - -```json -{ - "id": null, - "url": null -} -``` - +## V1 Item Image + +V1ItemImage + +### Structure + +`V1ItemImage` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The image's unique ID. | +| `url` | `String` | Optional | The image's publicly accessible URL. | + +### Example (as JSON) + +```json +{ + "id": null, + "url": null +} +``` + diff --git a/doc/models/v1-item-type.md b/doc/models/v1-item-type.md index 6bc97148..bafd77ae 100644 --- a/doc/models/v1-item-type.md +++ b/doc/models/v1-item-type.md @@ -1,14 +1,14 @@ -## V1 Item Type - -### Enumeration - -`V1ItemType` - -### Fields - -| Name | Description | -| --- | --- | -| `NORMAL` | - | -| `GIFT_CARD` | - | -| `OTHER` | - | - +## V1 Item Type + +### Enumeration + +`V1ItemType` + +### Fields + +| Name | Description | +| --- | --- | +| `NORMAL` | - | +| `GIFT_CARD` | - | +| `OTHER` | - | + diff --git a/doc/models/v1-item-visibility.md b/doc/models/v1-item-visibility.md index d75f3780..60dcffb1 100644 --- a/doc/models/v1-item-visibility.md +++ b/doc/models/v1-item-visibility.md @@ -1,13 +1,13 @@ -## V1 Item Visibility - -### Enumeration - -`V1ItemVisibility` - -### Fields - -| Name | Description | -| --- | --- | -| `PUBLIC` | - | -| `PRIVATE` | - | - +## V1 Item Visibility + +### Enumeration + +`V1ItemVisibility` + +### Fields + +| Name | Description | +| --- | --- | +| `PUBLIC` | - | +| `PRIVATE` | - | + diff --git a/doc/models/v1-item.md b/doc/models/v1-item.md index 216ddb11..29389251 100644 --- a/doc/models/v1-item.md +++ b/doc/models/v1-item.md @@ -1,54 +1,54 @@ -## V1 Item - -V1Item - -### Structure - -`V1Item` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The item's ID. Must be unique among all entity IDs ever provided on behalf of the merchant. You can never reuse an ID. This value can include alphanumeric characters, dashes (-), and underscores (_). | -| `name` | `String` | Optional | The item's name. | -| `description` | `String` | Optional | The item's description. | -| `type` | [`String (V1 Item Type)`](/doc/models/v1-item-type.md) | Optional | - | -| `color` | [`String (V1 Discount Color)`](/doc/models/v1-discount-color.md) | Optional | - | -| `abbreviation` | `String` | Optional | The text of the item's display label in Square Register. Only up to the first five characters of the string are used. | -| `visibility` | [`String (V1 Item Visibility)`](/doc/models/v1-item-visibility.md) | Optional | - | -| `available_online` | `Boolean` | Optional | If true, the item can be added to shipping orders from the merchant's online store. | -| `master_image` | [`V1 Item Image Hash`](/doc/models/v1-item-image.md) | Optional | V1ItemImage | -| `category` | [`V1 Category Hash`](/doc/models/v1-category.md) | Optional | V1Category | -| `variations` | [`Array`](/doc/models/v1-variation.md) | Optional | The item's variations. You must specify at least one variation. | -| `modifier_lists` | [`Array`](/doc/models/v1-modifier-list.md) | Optional | The modifier lists that apply to the item, if any. | -| `fees` | [`Array`](/doc/models/v1-fee.md) | Optional | The fees that apply to the item, if any. | -| `taxable` | `Boolean` | Optional | Deprecated. This field is not used. | -| `category_id` | `String` | Optional | The ID of the item's category, if any. | -| `available_for_pickup` | `Boolean` | Optional | If true, the item can be added to pickup orders from the merchant's online store. Default value: false | -| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null, - "description": null, - "type": null, - "color": null, - "abbreviation": null, - "visibility": null, - "available_online": null, - "master_image": null, - "category": null, - "variations": null, - "modifier_lists": null, - "fees": null, - "taxable": null, - "category_id": null, - "available_for_pickup": null, - "v2_id": null -} -``` - +## V1 Item + +V1Item + +### Structure + +`V1Item` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The item's ID. Must be unique among all entity IDs ever provided on behalf of the merchant. You can never reuse an ID. This value can include alphanumeric characters, dashes (-), and underscores (_). | +| `name` | `String` | Optional | The item's name. | +| `description` | `String` | Optional | The item's description. | +| `type` | [`String (V1 Item Type)`](/doc/models/v1-item-type.md) | Optional | - | +| `color` | [`String (V1 Discount Color)`](/doc/models/v1-discount-color.md) | Optional | - | +| `abbreviation` | `String` | Optional | The text of the item's display label in Square Register. Only up to the first five characters of the string are used. | +| `visibility` | [`String (V1 Item Visibility)`](/doc/models/v1-item-visibility.md) | Optional | - | +| `available_online` | `Boolean` | Optional | If true, the item can be added to shipping orders from the merchant's online store. | +| `master_image` | [`V1 Item Image Hash`](/doc/models/v1-item-image.md) | Optional | V1ItemImage | +| `category` | [`V1 Category Hash`](/doc/models/v1-category.md) | Optional | V1Category | +| `variations` | [`Array`](/doc/models/v1-variation.md) | Optional | The item's variations. You must specify at least one variation. | +| `modifier_lists` | [`Array`](/doc/models/v1-modifier-list.md) | Optional | The modifier lists that apply to the item, if any. | +| `fees` | [`Array`](/doc/models/v1-fee.md) | Optional | The fees that apply to the item, if any. | +| `taxable` | `Boolean` | Optional | Deprecated. This field is not used. | +| `category_id` | `String` | Optional | The ID of the item's category, if any. | +| `available_for_pickup` | `Boolean` | Optional | If true, the item can be added to pickup orders from the merchant's online store. Default value: false | +| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null, + "description": null, + "type": null, + "color": null, + "abbreviation": null, + "visibility": null, + "available_online": null, + "master_image": null, + "category": null, + "variations": null, + "modifier_lists": null, + "fees": null, + "taxable": null, + "category_id": null, + "available_for_pickup": null, + "v2_id": null +} +``` + diff --git a/doc/models/v1-list-bank-accounts-response.md b/doc/models/v1-list-bank-accounts-response.md index cb0e8e65..dd7efbcf 100644 --- a/doc/models/v1-list-bank-accounts-response.md +++ b/doc/models/v1-list-bank-accounts-response.md @@ -1,20 +1,20 @@ -## V1 List Bank Accounts Response - -### Structure - -`V1ListBankAccountsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-bank-account.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Bank Accounts Response + +### Structure + +`V1ListBankAccountsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-bank-account.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-cash-drawer-shifts-request.md b/doc/models/v1-list-cash-drawer-shifts-request.md index 2d8f0d51..338f467d 100644 --- a/doc/models/v1-list-cash-drawer-shifts-request.md +++ b/doc/models/v1-list-cash-drawer-shifts-request.md @@ -1,24 +1,24 @@ -## V1 List Cash Drawer Shifts Request - -### Structure - -`V1ListCashDrawerShiftsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time minus 90 days. | -| `end_time` | `String` | Optional | The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time. | - -### Example (as JSON) - -```json -{ - "order": null, - "begin_time": null, - "end_time": null -} -``` - +## V1 List Cash Drawer Shifts Request + +### Structure + +`V1ListCashDrawerShiftsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time minus 90 days. | +| `end_time` | `String` | Optional | The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time. | + +### Example (as JSON) + +```json +{ + "order": null, + "begin_time": null, + "end_time": null +} +``` + diff --git a/doc/models/v1-list-cash-drawer-shifts-response.md b/doc/models/v1-list-cash-drawer-shifts-response.md index fa349bed..78e8bcd9 100644 --- a/doc/models/v1-list-cash-drawer-shifts-response.md +++ b/doc/models/v1-list-cash-drawer-shifts-response.md @@ -1,20 +1,20 @@ -## V1 List Cash Drawer Shifts Response - -### Structure - -`V1ListCashDrawerShiftsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-cash-drawer-shift.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Cash Drawer Shifts Response + +### Structure + +`V1ListCashDrawerShiftsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-cash-drawer-shift.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-categories-response.md b/doc/models/v1-list-categories-response.md index 6289c7b6..f52e10e7 100644 --- a/doc/models/v1-list-categories-response.md +++ b/doc/models/v1-list-categories-response.md @@ -1,20 +1,20 @@ -## V1 List Categories Response - -### Structure - -`V1ListCategoriesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-category.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Categories Response + +### Structure + +`V1ListCategoriesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-category.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-discounts-response.md b/doc/models/v1-list-discounts-response.md index fbbd74ed..8fcc60eb 100644 --- a/doc/models/v1-list-discounts-response.md +++ b/doc/models/v1-list-discounts-response.md @@ -1,20 +1,20 @@ -## V1 List Discounts Response - -### Structure - -`V1ListDiscountsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-discount.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Discounts Response + +### Structure + +`V1ListDiscountsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-discount.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-employee-roles-request.md b/doc/models/v1-list-employee-roles-request.md index e56263df..680d6fe6 100644 --- a/doc/models/v1-list-employee-roles-request.md +++ b/doc/models/v1-list-employee-roles-request.md @@ -1,24 +1,24 @@ -## V1 List Employee Roles Request - -### Structure - -`V1ListEmployeeRolesRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `limit` | `Integer` | Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | -| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Example (as JSON) - -```json -{ - "order": null, - "limit": null, - "batch_token": null -} -``` - +## V1 List Employee Roles Request + +### Structure + +`V1ListEmployeeRolesRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `limit` | `Integer` | Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | +| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Example (as JSON) + +```json +{ + "order": null, + "limit": null, + "batch_token": null +} +``` + diff --git a/doc/models/v1-list-employee-roles-response.md b/doc/models/v1-list-employee-roles-response.md index d2d56af5..f6903c5a 100644 --- a/doc/models/v1-list-employee-roles-response.md +++ b/doc/models/v1-list-employee-roles-response.md @@ -1,20 +1,20 @@ -## V1 List Employee Roles Response - -### Structure - -`V1ListEmployeeRolesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-employee-role.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Employee Roles Response + +### Structure + +`V1ListEmployeeRolesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-employee-role.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-employees-request.md b/doc/models/v1-list-employees-request.md index afc133ec..340e752d 100644 --- a/doc/models/v1-list-employees-request.md +++ b/doc/models/v1-list-employees-request.md @@ -1,36 +1,36 @@ -## V1 List Employees Request - -### Structure - -`V1ListEmployeesRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `begin_updated_at` | `String` | Optional | If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format | -| `end_updated_at` | `String` | Optional | If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format. | -| `begin_created_at` | `String` | Optional | If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format. | -| `end_created_at` | `String` | Optional | If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format. | -| `status` | [`String (V1 Employee Status)`](/doc/models/v1-employee-status.md) | Optional | - | -| `external_id` | `String` | Optional | If provided, the endpoint returns only employee entities with the specified external_id. | -| `limit` | `Integer` | Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | -| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Example (as JSON) - -```json -{ - "order": null, - "begin_updated_at": null, - "end_updated_at": null, - "begin_created_at": null, - "end_created_at": null, - "status": null, - "external_id": null, - "limit": null, - "batch_token": null -} -``` - +## V1 List Employees Request + +### Structure + +`V1ListEmployeesRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `begin_updated_at` | `String` | Optional | If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format | +| `end_updated_at` | `String` | Optional | If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format. | +| `begin_created_at` | `String` | Optional | If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format. | +| `end_created_at` | `String` | Optional | If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format. | +| `status` | [`String (V1 Employee Status)`](/doc/models/v1-employee-status.md) | Optional | - | +| `external_id` | `String` | Optional | If provided, the endpoint returns only employee entities with the specified external_id. | +| `limit` | `Integer` | Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | +| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Example (as JSON) + +```json +{ + "order": null, + "begin_updated_at": null, + "end_updated_at": null, + "begin_created_at": null, + "end_created_at": null, + "status": null, + "external_id": null, + "limit": null, + "batch_token": null +} +``` + diff --git a/doc/models/v1-list-employees-response.md b/doc/models/v1-list-employees-response.md index 262bea14..00cc7a8c 100644 --- a/doc/models/v1-list-employees-response.md +++ b/doc/models/v1-list-employees-response.md @@ -1,20 +1,20 @@ -## V1 List Employees Response - -### Structure - -`V1ListEmployeesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-employee.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Employees Response + +### Structure + +`V1ListEmployeesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-employee.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-fees-response.md b/doc/models/v1-list-fees-response.md index aac2028d..64e5e56a 100644 --- a/doc/models/v1-list-fees-response.md +++ b/doc/models/v1-list-fees-response.md @@ -1,20 +1,20 @@ -## V1 List Fees Response - -### Structure - -`V1ListFeesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-fee.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Fees Response + +### Structure + +`V1ListFeesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-fee.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-inventory-request.md b/doc/models/v1-list-inventory-request.md index 2762c0d4..26cf6a39 100644 --- a/doc/models/v1-list-inventory-request.md +++ b/doc/models/v1-list-inventory-request.md @@ -1,22 +1,22 @@ -## V1 List Inventory Request - -### Structure - -`V1ListInventoryRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `limit` | `Integer` | Optional | The maximum number of inventory entries to return in a single response. This value cannot exceed 1000. | -| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Example (as JSON) - -```json -{ - "limit": null, - "batch_token": null -} -``` - +## V1 List Inventory Request + +### Structure + +`V1ListInventoryRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `limit` | `Integer` | Optional | The maximum number of inventory entries to return in a single response. This value cannot exceed 1000. | +| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Example (as JSON) + +```json +{ + "limit": null, + "batch_token": null +} +``` + diff --git a/doc/models/v1-list-inventory-response.md b/doc/models/v1-list-inventory-response.md index 59aa7e41..50e841d8 100644 --- a/doc/models/v1-list-inventory-response.md +++ b/doc/models/v1-list-inventory-response.md @@ -1,20 +1,20 @@ -## V1 List Inventory Response - -### Structure - -`V1ListInventoryResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-inventory-entry.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Inventory Response + +### Structure + +`V1ListInventoryResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-inventory-entry.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-items-request.md b/doc/models/v1-list-items-request.md index 65425399..cfbdded2 100644 --- a/doc/models/v1-list-items-request.md +++ b/doc/models/v1-list-items-request.md @@ -1,20 +1,20 @@ -## V1 List Items Request - -### Structure - -`V1ListItemsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Example (as JSON) - -```json -{ - "batch_token": null -} -``` - +## V1 List Items Request + +### Structure + +`V1ListItemsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Example (as JSON) + +```json +{ + "batch_token": null +} +``` + diff --git a/doc/models/v1-list-items-response.md b/doc/models/v1-list-items-response.md index f17ef1d5..7f07323f 100644 --- a/doc/models/v1-list-items-response.md +++ b/doc/models/v1-list-items-response.md @@ -1,20 +1,20 @@ -## V1 List Items Response - -### Structure - -`V1ListItemsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-item.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Items Response + +### Structure + +`V1ListItemsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-item.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-locations-response.md b/doc/models/v1-list-locations-response.md index 60aafa2f..affa437d 100644 --- a/doc/models/v1-list-locations-response.md +++ b/doc/models/v1-list-locations-response.md @@ -1,20 +1,20 @@ -## V1 List Locations Response - -### Structure - -`V1ListLocationsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-merchant.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Locations Response + +### Structure + +`V1ListLocationsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-merchant.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-modifier-lists-response.md b/doc/models/v1-list-modifier-lists-response.md index 3f05f6b8..ce907513 100644 --- a/doc/models/v1-list-modifier-lists-response.md +++ b/doc/models/v1-list-modifier-lists-response.md @@ -1,20 +1,20 @@ -## V1 List Modifier Lists Response - -### Structure - -`V1ListModifierListsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-modifier-list.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Modifier Lists Response + +### Structure + +`V1ListModifierListsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-modifier-list.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-orders-request.md b/doc/models/v1-list-orders-request.md index cf822cb8..183131de 100644 --- a/doc/models/v1-list-orders-request.md +++ b/doc/models/v1-list-orders-request.md @@ -1,24 +1,24 @@ -## V1 List Orders Request - -### Structure - -`V1ListOrdersRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `limit` | `Integer` | Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | -| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Example (as JSON) - -```json -{ - "order": null, - "limit": null, - "batch_token": null -} -``` - +## V1 List Orders Request + +### Structure + +`V1ListOrdersRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `limit` | `Integer` | Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | +| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Example (as JSON) + +```json +{ + "order": null, + "limit": null, + "batch_token": null +} +``` + diff --git a/doc/models/v1-list-orders-response.md b/doc/models/v1-list-orders-response.md index 7f7256b6..fe2ca5ee 100644 --- a/doc/models/v1-list-orders-response.md +++ b/doc/models/v1-list-orders-response.md @@ -1,20 +1,20 @@ -## V1 List Orders Response - -### Structure - -`V1ListOrdersResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-order.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Orders Response + +### Structure + +`V1ListOrdersResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-order.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-pages-response.md b/doc/models/v1-list-pages-response.md index 378b47d1..1e3991d2 100644 --- a/doc/models/v1-list-pages-response.md +++ b/doc/models/v1-list-pages-response.md @@ -1,20 +1,20 @@ -## V1 List Pages Response - -### Structure - -`V1ListPagesResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-page.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Pages Response + +### Structure + +`V1ListPagesResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-page.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-payments-request.md b/doc/models/v1-list-payments-request.md index 87ceb78f..9f6a7e40 100644 --- a/doc/models/v1-list-payments-request.md +++ b/doc/models/v1-list-payments-request.md @@ -1,30 +1,30 @@ -## V1 List Payments Request - -### Structure - -`V1ListPaymentsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `String` | Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `Integer` | Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | -| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | -| `include_partial` | `Boolean` | Optional | Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed. | - -### Example (as JSON) - -```json -{ - "order": null, - "begin_time": null, - "end_time": null, - "limit": null, - "batch_token": null, - "include_partial": null -} -``` - +## V1 List Payments Request + +### Structure + +`V1ListPaymentsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | +| `end_time` | `String` | Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | +| `limit` | `Integer` | Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | +| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | +| `include_partial` | `Boolean` | Optional | Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed. | + +### Example (as JSON) + +```json +{ + "order": null, + "begin_time": null, + "end_time": null, + "limit": null, + "batch_token": null, + "include_partial": null +} +``` + diff --git a/doc/models/v1-list-payments-response.md b/doc/models/v1-list-payments-response.md index 27fc1c39..5bf83f04 100644 --- a/doc/models/v1-list-payments-response.md +++ b/doc/models/v1-list-payments-response.md @@ -1,20 +1,20 @@ -## V1 List Payments Response - -### Structure - -`V1ListPaymentsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-payment.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Payments Response + +### Structure + +`V1ListPaymentsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-payment.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-refunds-request.md b/doc/models/v1-list-refunds-request.md index b81172c0..e126dabb 100644 --- a/doc/models/v1-list-refunds-request.md +++ b/doc/models/v1-list-refunds-request.md @@ -1,28 +1,28 @@ -## V1 List Refunds Request - -### Structure - -`V1ListRefundsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `String` | Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `Integer` | Optional | The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods. | -| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Example (as JSON) - -```json -{ - "order": null, - "begin_time": null, - "end_time": null, - "limit": null, - "batch_token": null -} -``` - +## V1 List Refunds Request + +### Structure + +`V1ListRefundsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | +| `end_time` | `String` | Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | +| `limit` | `Integer` | Optional | The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods. | +| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Example (as JSON) + +```json +{ + "order": null, + "begin_time": null, + "end_time": null, + "limit": null, + "batch_token": null +} +``` + diff --git a/doc/models/v1-list-refunds-response.md b/doc/models/v1-list-refunds-response.md index f8209655..068b2424 100644 --- a/doc/models/v1-list-refunds-response.md +++ b/doc/models/v1-list-refunds-response.md @@ -1,20 +1,20 @@ -## V1 List Refunds Response - -### Structure - -`V1ListRefundsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-refund.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Refunds Response + +### Structure + +`V1ListRefundsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-refund.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-settlements-request-status.md b/doc/models/v1-list-settlements-request-status.md index c5ed4409..72f343e1 100644 --- a/doc/models/v1-list-settlements-request-status.md +++ b/doc/models/v1-list-settlements-request-status.md @@ -1,13 +1,13 @@ -## V1 List Settlements Request Status - -### Enumeration - -`V1ListSettlementsRequestStatus` - -### Fields - -| Name | Description | -| --- | --- | -| `SENT` | - | -| `FAILED` | - | - +## V1 List Settlements Request Status + +### Enumeration + +`V1ListSettlementsRequestStatus` + +### Fields + +| Name | Description | +| --- | --- | +| `SENT` | - | +| `FAILED` | - | + diff --git a/doc/models/v1-list-settlements-request.md b/doc/models/v1-list-settlements-request.md index 2793a149..32a9ef6b 100644 --- a/doc/models/v1-list-settlements-request.md +++ b/doc/models/v1-list-settlements-request.md @@ -1,30 +1,30 @@ -## V1 List Settlements Request - -### Structure - -`V1ListSettlementsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `String` | Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `Integer` | Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | -| `status` | [`String (V1 List Settlements Request Status)`](/doc/models/v1-list-settlements-request-status.md) | Optional | - | -| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Example (as JSON) - -```json -{ - "order": null, - "begin_time": null, - "end_time": null, - "limit": null, - "status": null, - "batch_token": null -} -``` - +## V1 List Settlements Request + +### Structure + +`V1ListSettlementsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `begin_time` | `String` | Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | +| `end_time` | `String` | Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | +| `limit` | `Integer` | Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | +| `status` | [`String (V1 List Settlements Request Status)`](/doc/models/v1-list-settlements-request-status.md) | Optional | - | +| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Example (as JSON) + +```json +{ + "order": null, + "begin_time": null, + "end_time": null, + "limit": null, + "status": null, + "batch_token": null +} +``` + diff --git a/doc/models/v1-list-settlements-response.md b/doc/models/v1-list-settlements-response.md index 41141568..092d5cee 100644 --- a/doc/models/v1-list-settlements-response.md +++ b/doc/models/v1-list-settlements-response.md @@ -1,20 +1,20 @@ -## V1 List Settlements Response - -### Structure - -`V1ListSettlementsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-settlement.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Settlements Response + +### Structure + +`V1ListSettlementsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-settlement.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-timecard-events-response.md b/doc/models/v1-list-timecard-events-response.md index 41c03218..02264297 100644 --- a/doc/models/v1-list-timecard-events-response.md +++ b/doc/models/v1-list-timecard-events-response.md @@ -1,20 +1,20 @@ -## V1 List Timecard Events Response - -### Structure - -`V1ListTimecardEventsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-timecard-event.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Timecard Events Response + +### Structure + +`V1ListTimecardEventsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-timecard-event.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-list-timecards-request.md b/doc/models/v1-list-timecards-request.md index d3455081..d9674fb2 100644 --- a/doc/models/v1-list-timecards-request.md +++ b/doc/models/v1-list-timecards-request.md @@ -1,40 +1,40 @@ -## V1 List Timecards Request - -### Structure - -`V1ListTimecardsRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | -| `employee_id` | `String` | Optional | If provided, the endpoint returns only timecards for the employee with the specified ID. | -| `begin_clockin_time` | `String` | Optional | If filtering results by their clockin_time field, the beginning of the requested reporting period, in ISO 8601 format. | -| `end_clockin_time` | `String` | Optional | If filtering results by their clockin_time field, the end of the requested reporting period, in ISO 8601 format. | -| `begin_clockout_time` | `String` | Optional | If filtering results by their clockout_time field, the beginning of the requested reporting period, in ISO 8601 format. | -| `end_clockout_time` | `String` | Optional | If filtering results by their clockout_time field, the end of the requested reporting period, in ISO 8601 format. | -| `begin_updated_at` | `String` | Optional | If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format. | -| `end_updated_at` | `String` | Optional | If filtering results by their updated_at field, the end of the requested reporting period, in ISO 8601 format. | -| `deleted` | `Boolean` | Optional | If true, only deleted timecards are returned. If false, only valid timecards are returned.If you don't provide this parameter, both valid and deleted timecards are returned. | -| `limit` | `Integer` | Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | -| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Example (as JSON) - -```json -{ - "order": null, - "employee_id": null, - "begin_clockin_time": null, - "end_clockin_time": null, - "begin_clockout_time": null, - "end_clockout_time": null, - "begin_updated_at": null, - "end_updated_at": null, - "deleted": null, - "limit": null, - "batch_token": null -} -``` - +## V1 List Timecards Request + +### Structure + +`V1ListTimecardsRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | +| `employee_id` | `String` | Optional | If provided, the endpoint returns only timecards for the employee with the specified ID. | +| `begin_clockin_time` | `String` | Optional | If filtering results by their clockin_time field, the beginning of the requested reporting period, in ISO 8601 format. | +| `end_clockin_time` | `String` | Optional | If filtering results by their clockin_time field, the end of the requested reporting period, in ISO 8601 format. | +| `begin_clockout_time` | `String` | Optional | If filtering results by their clockout_time field, the beginning of the requested reporting period, in ISO 8601 format. | +| `end_clockout_time` | `String` | Optional | If filtering results by their clockout_time field, the end of the requested reporting period, in ISO 8601 format. | +| `begin_updated_at` | `String` | Optional | If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format. | +| `end_updated_at` | `String` | Optional | If filtering results by their updated_at field, the end of the requested reporting period, in ISO 8601 format. | +| `deleted` | `Boolean` | Optional | If true, only deleted timecards are returned. If false, only valid timecards are returned.If you don't provide this parameter, both valid and deleted timecards are returned. | +| `limit` | `Integer` | Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | +| `batch_token` | `String` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Example (as JSON) + +```json +{ + "order": null, + "employee_id": null, + "begin_clockin_time": null, + "end_clockin_time": null, + "begin_clockout_time": null, + "end_clockout_time": null, + "begin_updated_at": null, + "end_updated_at": null, + "deleted": null, + "limit": null, + "batch_token": null +} +``` + diff --git a/doc/models/v1-list-timecards-response.md b/doc/models/v1-list-timecards-response.md index 3c16a374..c83e3562 100644 --- a/doc/models/v1-list-timecards-response.md +++ b/doc/models/v1-list-timecards-response.md @@ -1,20 +1,20 @@ -## V1 List Timecards Response - -### Structure - -`V1ListTimecardsResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`Array`](/doc/models/v1-timecard.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "items": null -} -``` - +## V1 List Timecards Response + +### Structure + +`V1ListTimecardsResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `items` | [`Array`](/doc/models/v1-timecard.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "items": null +} +``` + diff --git a/doc/models/v1-merchant-account-type.md b/doc/models/v1-merchant-account-type.md index d1214a34..7e94d545 100644 --- a/doc/models/v1-merchant-account-type.md +++ b/doc/models/v1-merchant-account-type.md @@ -1,13 +1,13 @@ -## V1 Merchant Account Type - -### Enumeration - -`V1MerchantAccountType` - -### Fields - -| Name | Description | -| --- | --- | -| `LOCATION` | - | -| `BUSINESS` | - | - +## V1 Merchant Account Type + +### Enumeration + +`V1MerchantAccountType` + +### Fields + +| Name | Description | +| --- | --- | +| `LOCATION` | - | +| `BUSINESS` | - | + diff --git a/doc/models/v1-merchant-business-type.md b/doc/models/v1-merchant-business-type.md index 97600642..20187baa 100644 --- a/doc/models/v1-merchant-business-type.md +++ b/doc/models/v1-merchant-business-type.md @@ -1,61 +1,61 @@ -## V1 Merchant Business Type - -### Enumeration - -`V1MerchantBusinessType` - -### Fields - -| Name | Description | -| --- | --- | -| `ACCOUNTING` | - | -| `APPAREL_AND_ACCESSORY_SHOPS` | - | -| `ART_DEALERS_GALLERIES` | - | -| `ART_DESIGN_AND_PHOTOGRAPHY` | - | -| `BAR_CLUB_LOUNGE` | - | -| `BEAUTY_AND_BARBER_SHOPS` | - | -| `BOOK_STORES` | - | -| `BUSINESS_SERVICES` | - | -| `CATERING` | - | -| `CHARITABLE_SOCIAL_SERVICE_ORGANIZATIONS` | - | -| `CHARITIBLE_ORGS` | - | -| `CLEANING_SERVICES` | - | -| `COMPUTER_EQUIPMENT_SOFTWARE_MAINTENANCE_REPAIR_SERVICES` | - | -| `CONSULTANT` | - | -| `CONTRACTORS` | - | -| `DELIVERY_SERVICES` | - | -| `DENTISTRY` | - | -| `EDUCATION` | - | -| `FOOD_STORES_CONVENIENCE_STORES_AND_SPECIALTY_MARKETS` | - | -| `FOOD_TRUCK_CART` | - | -| `FURNITURE_HOME_AND_OFFICE_EQUIPMENT` | - | -| `FURNITURE_HOME_GOODS` | - | -| `HOTELS_AND_LODGING` | - | -| `INDIVIDUAL_USE` | - | -| `JEWELRY_AND_WATCHES` | - | -| `LANDSCAPING_AND_HORTICULTURAL_SERVICES` | - | -| `LANGUAGE_SCHOOLS` | - | -| `LEGAL_SERVICES` | - | -| `MEDICAL_PRACTITIONERS` | - | -| `MEDICAL_SERVICES_AND_HEALTH_PRACTITIONERS` | - | -| `MEMBERSHIP_ORGANIZATIONS` | - | -| `MUSIC_AND_ENTERTAINMENT` | - | -| `OTHER` | - | -| `OUTDOOR_MARKETS` | - | -| `PERSONAL_SERVICES` | - | -| `POLITICAL_ORGANIZATIONS` | - | -| `PROFESSIONAL_SERVICES` | - | -| `REAL_ESTATE` | - | -| `RECREATION_SERVICES` | - | -| `REPAIR_SHOPS_AND_RELATED_SERVICES` | - | -| `RESTAURANTS` | - | -| `RETAIL_SHOPS` | - | -| `SCHOOLS_AND_EDUCATIONAL_SERVICES` | - | -| `SPORTING_GOODS` | - | -| `TAXICABS_AND_LIMOUSINES` | - | -| `TICKET_SALES` | - | -| `TOURISM` | - | -| `TRAVEL_TOURISM` | - | -| `VETERINARY_SERVICES` | - | -| `WEB_DEV_DESIGN` | - | - +## V1 Merchant Business Type + +### Enumeration + +`V1MerchantBusinessType` + +### Fields + +| Name | Description | +| --- | --- | +| `ACCOUNTING` | - | +| `APPAREL_AND_ACCESSORY_SHOPS` | - | +| `ART_DEALERS_GALLERIES` | - | +| `ART_DESIGN_AND_PHOTOGRAPHY` | - | +| `BAR_CLUB_LOUNGE` | - | +| `BEAUTY_AND_BARBER_SHOPS` | - | +| `BOOK_STORES` | - | +| `BUSINESS_SERVICES` | - | +| `CATERING` | - | +| `CHARITABLE_SOCIAL_SERVICE_ORGANIZATIONS` | - | +| `CHARITIBLE_ORGS` | - | +| `CLEANING_SERVICES` | - | +| `COMPUTER_EQUIPMENT_SOFTWARE_MAINTENANCE_REPAIR_SERVICES` | - | +| `CONSULTANT` | - | +| `CONTRACTORS` | - | +| `DELIVERY_SERVICES` | - | +| `DENTISTRY` | - | +| `EDUCATION` | - | +| `FOOD_STORES_CONVENIENCE_STORES_AND_SPECIALTY_MARKETS` | - | +| `FOOD_TRUCK_CART` | - | +| `FURNITURE_HOME_AND_OFFICE_EQUIPMENT` | - | +| `FURNITURE_HOME_GOODS` | - | +| `HOTELS_AND_LODGING` | - | +| `INDIVIDUAL_USE` | - | +| `JEWELRY_AND_WATCHES` | - | +| `LANDSCAPING_AND_HORTICULTURAL_SERVICES` | - | +| `LANGUAGE_SCHOOLS` | - | +| `LEGAL_SERVICES` | - | +| `MEDICAL_PRACTITIONERS` | - | +| `MEDICAL_SERVICES_AND_HEALTH_PRACTITIONERS` | - | +| `MEMBERSHIP_ORGANIZATIONS` | - | +| `MUSIC_AND_ENTERTAINMENT` | - | +| `OTHER` | - | +| `OUTDOOR_MARKETS` | - | +| `PERSONAL_SERVICES` | - | +| `POLITICAL_ORGANIZATIONS` | - | +| `PROFESSIONAL_SERVICES` | - | +| `REAL_ESTATE` | - | +| `RECREATION_SERVICES` | - | +| `REPAIR_SHOPS_AND_RELATED_SERVICES` | - | +| `RESTAURANTS` | - | +| `RETAIL_SHOPS` | - | +| `SCHOOLS_AND_EDUCATIONAL_SERVICES` | - | +| `SPORTING_GOODS` | - | +| `TAXICABS_AND_LIMOUSINES` | - | +| `TICKET_SALES` | - | +| `TOURISM` | - | +| `TRAVEL_TOURISM` | - | +| `VETERINARY_SERVICES` | - | +| `WEB_DEV_DESIGN` | - | + diff --git a/doc/models/v1-merchant-location-details.md b/doc/models/v1-merchant-location-details.md index 99fa5e36..bb264a14 100644 --- a/doc/models/v1-merchant-location-details.md +++ b/doc/models/v1-merchant-location-details.md @@ -1,22 +1,22 @@ -## V1 Merchant Location Details - -Additional information for a single-location account specified by its associated business account, if it has one. - -### Structure - -`V1MerchantLocationDetails` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `nickname` | `String` | Optional | The nickname assigned to the single-location account by the parent business. This value appears in the parent business's multi-location dashboard. | - -### Example (as JSON) - -```json -{ - "nickname": null -} -``` - +## V1 Merchant Location Details + +Additional information for a single-location account specified by its associated business account, if it has one. + +### Structure + +`V1MerchantLocationDetails` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `nickname` | `String` | Optional | The nickname assigned to the single-location account by the parent business. This value appears in the parent business's multi-location dashboard. | + +### Example (as JSON) + +```json +{ + "nickname": null +} +``` + diff --git a/doc/models/v1-merchant.md b/doc/models/v1-merchant.md index a335a3ca..1dd8146d 100644 --- a/doc/models/v1-merchant.md +++ b/doc/models/v1-merchant.md @@ -1,51 +1,51 @@ -## V1 Merchant - -Defines the fields that are included in the response body of -a request to the **RetrieveBusiness** endpoint. - -### Structure - -`V1Merchant` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The merchant account's unique identifier. | -| `name` | `String` | Optional | The name associated with the merchant account. | -| `email` | `String` | Optional | The email address associated with the merchant account. | -| `account_type` | [`String (V1 Merchant Account Type)`](/doc/models/v1-merchant-account-type.md) | Optional | - | -| `account_capabilities` | `Array` | Optional | Capabilities that are enabled for the merchant's Square account. Capabilities that are not listed in this array are not enabled for the account. | -| `country_code` | `String` | Optional | The country associated with the merchant account, in ISO 3166-1-alpha-2 format. | -| `language_code` | `String` | Optional | The language associated with the merchant account, in BCP 47 format. | -| `currency_code` | `String` | Optional | The currency associated with the merchant account, in ISO 4217 format. For example, the currency code for US dollars is USD. | -| `business_name` | `String` | Optional | The name of the merchant's business. | -| `business_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `business_phone` | [`V1 Phone Number Hash`](/doc/models/v1-phone-number.md) | Optional | Represents a phone number. | -| `business_type` | [`String (V1 Merchant Business Type)`](/doc/models/v1-merchant-business-type.md) | Optional | - | -| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `location_details` | [`V1 Merchant Location Details Hash`](/doc/models/v1-merchant-location-details.md) | Optional | Additional information for a single-location account specified by its associated business account, if it has one. | -| `market_url` | `String` | Optional | The URL of the merchant's online store. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null, - "email": null, - "account_type": null, - "account_capabilities": null, - "country_code": null, - "language_code": null, - "currency_code": null, - "business_name": null, - "business_address": null, - "business_phone": null, - "business_type": null, - "shipping_address": null, - "location_details": null, - "market_url": null -} -``` - +## V1 Merchant + +Defines the fields that are included in the response body of +a request to the **RetrieveBusiness** endpoint. + +### Structure + +`V1Merchant` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The merchant account's unique identifier. | +| `name` | `String` | Optional | The name associated with the merchant account. | +| `email` | `String` | Optional | The email address associated with the merchant account. | +| `account_type` | [`String (V1 Merchant Account Type)`](/doc/models/v1-merchant-account-type.md) | Optional | - | +| `account_capabilities` | `Array` | Optional | Capabilities that are enabled for the merchant's Square account. Capabilities that are not listed in this array are not enabled for the account. | +| `country_code` | `String` | Optional | The country associated with the merchant account, in ISO 3166-1-alpha-2 format. | +| `language_code` | `String` | Optional | The language associated with the merchant account, in BCP 47 format. | +| `currency_code` | `String` | Optional | The currency associated with the merchant account, in ISO 4217 format. For example, the currency code for US dollars is USD. | +| `business_name` | `String` | Optional | The name of the merchant's business. | +| `business_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `business_phone` | [`V1 Phone Number Hash`](/doc/models/v1-phone-number.md) | Optional | Represents a phone number. | +| `business_type` | [`String (V1 Merchant Business Type)`](/doc/models/v1-merchant-business-type.md) | Optional | - | +| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `location_details` | [`V1 Merchant Location Details Hash`](/doc/models/v1-merchant-location-details.md) | Optional | Additional information for a single-location account specified by its associated business account, if it has one. | +| `market_url` | `String` | Optional | The URL of the merchant's online store. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null, + "email": null, + "account_type": null, + "account_capabilities": null, + "country_code": null, + "language_code": null, + "currency_code": null, + "business_name": null, + "business_address": null, + "business_phone": null, + "business_type": null, + "shipping_address": null, + "location_details": null, + "market_url": null +} +``` + diff --git a/doc/models/v1-modifier-list-selection-type.md b/doc/models/v1-modifier-list-selection-type.md index 3e26bcfd..45d25dbd 100644 --- a/doc/models/v1-modifier-list-selection-type.md +++ b/doc/models/v1-modifier-list-selection-type.md @@ -1,13 +1,13 @@ -## V1 Modifier List Selection Type - -### Enumeration - -`V1ModifierListSelectionType` - -### Fields - -| Name | Description | -| --- | --- | -| `SINGLE` | - | -| `MULTIPLE` | - | - +## V1 Modifier List Selection Type + +### Enumeration + +`V1ModifierListSelectionType` + +### Fields + +| Name | Description | +| --- | --- | +| `SINGLE` | - | +| `MULTIPLE` | - | + diff --git a/doc/models/v1-modifier-list.md b/doc/models/v1-modifier-list.md index b4ed4a88..7b0c95c0 100644 --- a/doc/models/v1-modifier-list.md +++ b/doc/models/v1-modifier-list.md @@ -1,30 +1,30 @@ -## V1 Modifier List - -V1ModifierList - -### Structure - -`V1ModifierList` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The modifier list's unique ID. | -| `name` | `String` | Optional | The modifier list's name. | -| `selection_type` | [`String (V1 Modifier List Selection Type)`](/doc/models/v1-modifier-list-selection-type.md) | Optional | - | -| `modifier_options` | [`Array`](/doc/models/v1-modifier-option.md) | Optional | The options included in the modifier list. | -| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null, - "selection_type": null, - "modifier_options": null, - "v2_id": null -} -``` - +## V1 Modifier List + +V1ModifierList + +### Structure + +`V1ModifierList` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The modifier list's unique ID. | +| `name` | `String` | Optional | The modifier list's name. | +| `selection_type` | [`String (V1 Modifier List Selection Type)`](/doc/models/v1-modifier-list-selection-type.md) | Optional | - | +| `modifier_options` | [`Array`](/doc/models/v1-modifier-option.md) | Optional | The options included in the modifier list. | +| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null, + "selection_type": null, + "modifier_options": null, + "v2_id": null +} +``` + diff --git a/doc/models/v1-modifier-option.md b/doc/models/v1-modifier-option.md index 65f3f245..1df170d5 100644 --- a/doc/models/v1-modifier-option.md +++ b/doc/models/v1-modifier-option.md @@ -1,34 +1,34 @@ -## V1 Modifier Option - -V1ModifierOption - -### Structure - -`V1ModifierOption` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The modifier option's unique ID. | -| `name` | `String` | Optional | The modifier option's name. | -| `price_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `on_by_default` | `Boolean` | Optional | If true, the modifier option is the default option in a modifier list for which selection_type is SINGLE. | -| `ordinal` | `Integer` | Optional | Indicates the modifier option's list position when displayed in Square Register and the merchant dashboard. If more than one modifier option in the same modifier list has the same ordinal value, those options are displayed in alphabetical order. | -| `modifier_list_id` | `String` | Optional | The ID of the modifier list the option belongs to. | -| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null, - "price_money": null, - "on_by_default": null, - "ordinal": null, - "modifier_list_id": null, - "v2_id": null -} -``` - +## V1 Modifier Option + +V1ModifierOption + +### Structure + +`V1ModifierOption` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The modifier option's unique ID. | +| `name` | `String` | Optional | The modifier option's name. | +| `price_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `on_by_default` | `Boolean` | Optional | If true, the modifier option is the default option in a modifier list for which selection_type is SINGLE. | +| `ordinal` | `Integer` | Optional | Indicates the modifier option's list position when displayed in Square Register and the merchant dashboard. If more than one modifier option in the same modifier list has the same ordinal value, those options are displayed in alphabetical order. | +| `modifier_list_id` | `String` | Optional | The ID of the modifier list the option belongs to. | +| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null, + "price_money": null, + "on_by_default": null, + "ordinal": null, + "modifier_list_id": null, + "v2_id": null +} +``` + diff --git a/doc/models/v1-money.md b/doc/models/v1-money.md index 2873581c..15902e7e 100644 --- a/doc/models/v1-money.md +++ b/doc/models/v1-money.md @@ -1,22 +1,22 @@ -## V1 Money - -### Structure - -`V1Money` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `amount` | `Integer` | Optional | Amount in the lowest denominated value of this Currency. E.g. in USD
these are cents, in JPY they are Yen (which do not have a 'cent' concept). | -| `currency_code` | [`String (Currency)`](/doc/models/currency.md) | Optional | Indicates the associated currency for an amount of money. Values correspond
to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). | - -### Example (as JSON) - -```json -{ - "amount": null, - "currency_code": null -} -``` - +## V1 Money + +### Structure + +`V1Money` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `amount` | `Integer` | Optional | Amount in the lowest denominated value of this Currency. E.g. in USD
these are cents, in JPY they are Yen (which do not have a 'cent' concept). | +| `currency_code` | [`String (Currency)`](/doc/models/currency.md) | Optional | Indicates the associated currency for an amount of money. Values correspond
to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). | + +### Example (as JSON) + +```json +{ + "amount": null, + "currency_code": null +} +``` + diff --git a/doc/models/v1-order-history-entry-action.md b/doc/models/v1-order-history-entry-action.md index 1703b0c6..b1d59d17 100644 --- a/doc/models/v1-order-history-entry-action.md +++ b/doc/models/v1-order-history-entry-action.md @@ -1,18 +1,18 @@ -## V1 Order History Entry Action - -### Enumeration - -`V1OrderHistoryEntryAction` - -### Fields - -| Name | Description | -| --- | --- | -| `ORDER_PLACED` | - | -| `DECLINED` | - | -| `PAYMENT_RECEIVED` | - | -| `CANCELED` | - | -| `COMPLETED` | - | -| `REFUNDED` | - | -| `EXPIRED` | - | - +## V1 Order History Entry Action + +### Enumeration + +`V1OrderHistoryEntryAction` + +### Fields + +| Name | Description | +| --- | --- | +| `ORDER_PLACED` | - | +| `DECLINED` | - | +| `PAYMENT_RECEIVED` | - | +| `CANCELED` | - | +| `COMPLETED` | - | +| `REFUNDED` | - | +| `EXPIRED` | - | + diff --git a/doc/models/v1-order-history-entry.md b/doc/models/v1-order-history-entry.md index a447d501..3b4d1a01 100644 --- a/doc/models/v1-order-history-entry.md +++ b/doc/models/v1-order-history-entry.md @@ -1,24 +1,24 @@ -## V1 Order History Entry - -V1OrderHistoryEntry - -### Structure - -`V1OrderHistoryEntry` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `action` | [`String (V1 Order History Entry Action)`](/doc/models/v1-order-history-entry-action.md) | Optional | - | -| `created_at` | `String` | Optional | The time when the action was performed, in ISO 8601 format. | - -### Example (as JSON) - -```json -{ - "action": null, - "created_at": null -} -``` - +## V1 Order History Entry + +V1OrderHistoryEntry + +### Structure + +`V1OrderHistoryEntry` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `action` | [`String (V1 Order History Entry Action)`](/doc/models/v1-order-history-entry-action.md) | Optional | - | +| `created_at` | `String` | Optional | The time when the action was performed, in ISO 8601 format. | + +### Example (as JSON) + +```json +{ + "action": null, + "created_at": null +} +``` + diff --git a/doc/models/v1-order-state.md b/doc/models/v1-order-state.md index 412955d9..e1adddcc 100644 --- a/doc/models/v1-order-state.md +++ b/doc/models/v1-order-state.md @@ -1,17 +1,17 @@ -## V1 Order State - -### Enumeration - -`V1OrderState` - -### Fields - -| Name | Description | -| --- | --- | -| `PENDING` | - | -| `OPEN` | - | -| `COMPLETED` | - | -| `CANCELED` | - | -| `REFUNDED` | - | -| `REJECTED` | - | - +## V1 Order State + +### Enumeration + +`V1OrderState` + +### Fields + +| Name | Description | +| --- | --- | +| `PENDING` | - | +| `OPEN` | - | +| `COMPLETED` | - | +| `CANCELED` | - | +| `REFUNDED` | - | +| `REJECTED` | - | + diff --git a/doc/models/v1-order.md b/doc/models/v1-order.md index 211f7f43..82363459 100644 --- a/doc/models/v1-order.md +++ b/doc/models/v1-order.md @@ -1,70 +1,70 @@ -## V1 Order - -V1Order - -### Structure - -`V1Order` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `id` | `String` | Optional | The order's unique identifier. | -| `buyer_email` | `String` | Optional | The email address of the order's buyer. | -| `recipient_name` | `String` | Optional | The name of the order's buyer. | -| `recipient_phone_number` | `String` | Optional | The phone number to use for the order's delivery. | -| `state` | [`String (V1 Order State)`](/doc/models/v1-order-state.md) | Optional | - | -| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | -| `subtotal_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `total_shipping_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `total_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `total_price_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `total_discount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `created_at` | `String` | Optional | The time when the order was created, in ISO 8601 format. | -| `updated_at` | `String` | Optional | The time when the order was last modified, in ISO 8601 format. | -| `expires_at` | `String` | Optional | The time when the order expires if no action is taken, in ISO 8601 format. | -| `payment_id` | `String` | Optional | The unique identifier of the payment associated with the order. | -| `buyer_note` | `String` | Optional | A note provided by the buyer when the order was created, if any. | -| `completed_note` | `String` | Optional | A note provided by the merchant when the order's state was set to COMPLETED, if any | -| `refunded_note` | `String` | Optional | A note provided by the merchant when the order's state was set to REFUNDED, if any. | -| `canceled_note` | `String` | Optional | A note provided by the merchant when the order's state was set to CANCELED, if any. | -| `tender` | [`V1 Tender Hash`](/doc/models/v1-tender.md) | Optional | A tender represents a discrete monetary exchange. Square represents this
exchange as a money object with a specific currency and amount, where the
amount is given in the smallest denomination of the given currency.

Square POS can accept more than one form of tender for a single payment (such
as by splitting a bill between a credit card and a gift card). The `tender`
field of the Payment object lists all forms of tender used for the payment.

Split tender payments behave slightly differently from single tender payments:

The receipt_url for a split tender corresponds only to the first tender listed
in the tender field. To get the receipt URLs for the remaining tenders, use
the receipt_url fields of the corresponding Tender objects.

*A note on gift cards**: when a customer purchases a Square gift card from a
merchant, the merchant receives the full amount of the gift card in the
associated payment.

When that gift card is used as a tender, the balance of the gift card is
reduced and the merchant receives no funds. A `Tender` object with a type of
`SQUARE_GIFT_CARD` indicates a gift card was used for some or all of the
associated payment. | -| `order_history` | [`Array`](/doc/models/v1-order-history-entry.md) | Optional | The history of actions associated with the order. | -| `promo_code` | `String` | Optional | The promo code provided by the buyer, if any. | -| `btc_receive_address` | `String` | Optional | For Bitcoin transactions, the address that the buyer sent Bitcoin to. | -| `btc_price_satoshi` | `Float` | Optional | For Bitcoin transactions, the price of the buyer's order in satoshi (100 million satoshi equals 1 BTC). | - -### Example (as JSON) - -```json -{ - "errors": null, - "id": null, - "buyer_email": null, - "recipient_name": null, - "recipient_phone_number": null, - "state": null, - "shipping_address": null, - "subtotal_money": null, - "total_shipping_money": null, - "total_tax_money": null, - "total_price_money": null, - "total_discount_money": null, - "created_at": null, - "updated_at": null, - "expires_at": null, - "payment_id": null, - "buyer_note": null, - "completed_note": null, - "refunded_note": null, - "canceled_note": null, - "tender": null, - "order_history": null, - "promo_code": null, - "btc_receive_address": null, - "btc_price_satoshi": null -} -``` - +## V1 Order + +V1Order + +### Structure + +`V1Order` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `id` | `String` | Optional | The order's unique identifier. | +| `buyer_email` | `String` | Optional | The email address of the order's buyer. | +| `recipient_name` | `String` | Optional | The name of the order's buyer. | +| `recipient_phone_number` | `String` | Optional | The phone number to use for the order's delivery. | +| `state` | [`String (V1 Order State)`](/doc/models/v1-order-state.md) | Optional | - | +| `shipping_address` | [`Address Hash`](/doc/models/address.md) | Optional | Represents a physical address. | +| `subtotal_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `total_shipping_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `total_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `total_price_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `total_discount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `created_at` | `String` | Optional | The time when the order was created, in ISO 8601 format. | +| `updated_at` | `String` | Optional | The time when the order was last modified, in ISO 8601 format. | +| `expires_at` | `String` | Optional | The time when the order expires if no action is taken, in ISO 8601 format. | +| `payment_id` | `String` | Optional | The unique identifier of the payment associated with the order. | +| `buyer_note` | `String` | Optional | A note provided by the buyer when the order was created, if any. | +| `completed_note` | `String` | Optional | A note provided by the merchant when the order's state was set to COMPLETED, if any | +| `refunded_note` | `String` | Optional | A note provided by the merchant when the order's state was set to REFUNDED, if any. | +| `canceled_note` | `String` | Optional | A note provided by the merchant when the order's state was set to CANCELED, if any. | +| `tender` | [`V1 Tender Hash`](/doc/models/v1-tender.md) | Optional | A tender represents a discrete monetary exchange. Square represents this
exchange as a money object with a specific currency and amount, where the
amount is given in the smallest denomination of the given currency.

Square POS can accept more than one form of tender for a single payment (such
as by splitting a bill between a credit card and a gift card). The `tender`
field of the Payment object lists all forms of tender used for the payment.

Split tender payments behave slightly differently from single tender payments:

The receipt_url for a split tender corresponds only to the first tender listed
in the tender field. To get the receipt URLs for the remaining tenders, use
the receipt_url fields of the corresponding Tender objects.

*A note on gift cards**: when a customer purchases a Square gift card from a
merchant, the merchant receives the full amount of the gift card in the
associated payment.

When that gift card is used as a tender, the balance of the gift card is
reduced and the merchant receives no funds. A `Tender` object with a type of
`SQUARE_GIFT_CARD` indicates a gift card was used for some or all of the
associated payment. | +| `order_history` | [`Array`](/doc/models/v1-order-history-entry.md) | Optional | The history of actions associated with the order. | +| `promo_code` | `String` | Optional | The promo code provided by the buyer, if any. | +| `btc_receive_address` | `String` | Optional | For Bitcoin transactions, the address that the buyer sent Bitcoin to. | +| `btc_price_satoshi` | `Float` | Optional | For Bitcoin transactions, the price of the buyer's order in satoshi (100 million satoshi equals 1 BTC). | + +### Example (as JSON) + +```json +{ + "errors": null, + "id": null, + "buyer_email": null, + "recipient_name": null, + "recipient_phone_number": null, + "state": null, + "shipping_address": null, + "subtotal_money": null, + "total_shipping_money": null, + "total_tax_money": null, + "total_price_money": null, + "total_discount_money": null, + "created_at": null, + "updated_at": null, + "expires_at": null, + "payment_id": null, + "buyer_note": null, + "completed_note": null, + "refunded_note": null, + "canceled_note": null, + "tender": null, + "order_history": null, + "promo_code": null, + "btc_receive_address": null, + "btc_price_satoshi": null +} +``` + diff --git a/doc/models/v1-page-cell-object-type.md b/doc/models/v1-page-cell-object-type.md index 176dfb9b..cab0334b 100644 --- a/doc/models/v1-page-cell-object-type.md +++ b/doc/models/v1-page-cell-object-type.md @@ -1,15 +1,15 @@ -## V1 Page Cell Object Type - -### Enumeration - -`V1PageCellObjectType` - -### Fields - -| Name | Description | -| --- | --- | -| `ITEM` | - | -| `DISCOUNT` | - | -| `CATEGORY` | - | -| `PLACEHOLDER` | - | - +## V1 Page Cell Object Type + +### Enumeration + +`V1PageCellObjectType` + +### Fields + +| Name | Description | +| --- | --- | +| `ITEM` | - | +| `DISCOUNT` | - | +| `CATEGORY` | - | +| `PLACEHOLDER` | - | + diff --git a/doc/models/v1-page-cell-placeholder-type.md b/doc/models/v1-page-cell-placeholder-type.md index b92fbd0e..62be104e 100644 --- a/doc/models/v1-page-cell-placeholder-type.md +++ b/doc/models/v1-page-cell-placeholder-type.md @@ -1,14 +1,14 @@ -## V1 Page Cell Placeholder Type - -### Enumeration - -`V1PageCellPlaceholderType` - -### Fields - -| Name | Description | -| --- | --- | -| `ALL_ITEMS` | - | -| `DISCOUNTS_CATEGORY` | - | -| `REWARDS_FINDER` | - | - +## V1 Page Cell Placeholder Type + +### Enumeration + +`V1PageCellPlaceholderType` + +### Fields + +| Name | Description | +| --- | --- | +| `ALL_ITEMS` | - | +| `DISCOUNTS_CATEGORY` | - | +| `REWARDS_FINDER` | - | + diff --git a/doc/models/v1-page-cell.md b/doc/models/v1-page-cell.md index e998c115..a1433fc3 100644 --- a/doc/models/v1-page-cell.md +++ b/doc/models/v1-page-cell.md @@ -1,32 +1,32 @@ -## V1 Page Cell - -V1PageCell - -### Structure - -`V1PageCell` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `page_id` | `String` | Optional | The unique identifier of the page the cell is included on. | -| `row` | `Integer` | Optional | The row of the cell. Always an integer between 0 and 4, inclusive. | -| `column` | `Integer` | Optional | The column of the cell. Always an integer between 0 and 4, inclusive. | -| `object_type` | [`String (V1 Page Cell Object Type)`](/doc/models/v1-page-cell-object-type.md) | Optional | - | -| `object_id` | `String` | Optional | The unique identifier of the entity represented in the cell. Not present for cells with an object_type of PLACEHOLDER. | -| `placeholder_type` | [`String (V1 Page Cell Placeholder Type)`](/doc/models/v1-page-cell-placeholder-type.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "page_id": null, - "row": null, - "column": null, - "object_type": null, - "object_id": null, - "placeholder_type": null -} -``` - +## V1 Page Cell + +V1PageCell + +### Structure + +`V1PageCell` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `page_id` | `String` | Optional | The unique identifier of the page the cell is included on. | +| `row` | `Integer` | Optional | The row of the cell. Always an integer between 0 and 4, inclusive. | +| `column` | `Integer` | Optional | The column of the cell. Always an integer between 0 and 4, inclusive. | +| `object_type` | [`String (V1 Page Cell Object Type)`](/doc/models/v1-page-cell-object-type.md) | Optional | - | +| `object_id` | `String` | Optional | The unique identifier of the entity represented in the cell. Not present for cells with an object_type of PLACEHOLDER. | +| `placeholder_type` | [`String (V1 Page Cell Placeholder Type)`](/doc/models/v1-page-cell-placeholder-type.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "page_id": null, + "row": null, + "column": null, + "object_type": null, + "object_id": null, + "placeholder_type": null +} +``` + diff --git a/doc/models/v1-page.md b/doc/models/v1-page.md index 3bd659c8..cc16d2e0 100644 --- a/doc/models/v1-page.md +++ b/doc/models/v1-page.md @@ -1,28 +1,28 @@ -## V1 Page - -V1Page - -### Structure - -`V1Page` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The page's unique identifier. | -| `name` | `String` | Optional | The page's name, if any. | -| `page_index` | `Integer` | Optional | The page's position in the merchant's list of pages. Always an integer between 0 and 6, inclusive. | -| `cells` | [`Array`](/doc/models/v1-page-cell.md) | Optional | The cells included on the page. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null, - "page_index": null, - "cells": null -} -``` - +## V1 Page + +V1Page + +### Structure + +`V1Page` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The page's unique identifier. | +| `name` | `String` | Optional | The page's name, if any. | +| `page_index` | `Integer` | Optional | The page's position in the merchant's list of pages. Always an integer between 0 and 6, inclusive. | +| `cells` | [`Array`](/doc/models/v1-page-cell.md) | Optional | The cells included on the page. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null, + "page_index": null, + "cells": null +} +``` + diff --git a/doc/models/v1-payment-discount.md b/doc/models/v1-payment-discount.md index 27e4e7a7..3a261ec5 100644 --- a/doc/models/v1-payment-discount.md +++ b/doc/models/v1-payment-discount.md @@ -1,26 +1,26 @@ -## V1 Payment Discount - -V1PaymentDiscount - -### Structure - -`V1PaymentDiscount` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The discount's name. | -| `applied_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `discount_id` | `String` | Optional | The ID of the applied discount, if available. Discounts applied in older versions of Square Register might not have an ID. | - -### Example (as JSON) - -```json -{ - "name": null, - "applied_money": null, - "discount_id": null -} -``` - +## V1 Payment Discount + +V1PaymentDiscount + +### Structure + +`V1PaymentDiscount` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The discount's name. | +| `applied_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `discount_id` | `String` | Optional | The ID of the applied discount, if available. Discounts applied in older versions of Square Register might not have an ID. | + +### Example (as JSON) + +```json +{ + "name": null, + "applied_money": null, + "discount_id": null +} +``` + diff --git a/doc/models/v1-payment-item-detail.md b/doc/models/v1-payment-item-detail.md index 72372c3c..b38247c2 100644 --- a/doc/models/v1-payment-item-detail.md +++ b/doc/models/v1-payment-item-detail.md @@ -1,28 +1,28 @@ -## V1 Payment Item Detail - -V1PaymentItemDetail - -### Structure - -`V1PaymentItemDetail` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `category_name` | `String` | Optional | The name of the item's merchant-defined category, if any. | -| `sku` | `String` | Optional | The item's merchant-defined SKU, if any. | -| `item_id` | `String` | Optional | The unique ID of the item purchased, if any. | -| `item_variation_id` | `String` | Optional | The unique ID of the item variation purchased, if any. | - -### Example (as JSON) - -```json -{ - "category_name": null, - "sku": null, - "item_id": null, - "item_variation_id": null -} -``` - +## V1 Payment Item Detail + +V1PaymentItemDetail + +### Structure + +`V1PaymentItemDetail` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `category_name` | `String` | Optional | The name of the item's merchant-defined category, if any. | +| `sku` | `String` | Optional | The item's merchant-defined SKU, if any. | +| `item_id` | `String` | Optional | The unique ID of the item purchased, if any. | +| `item_variation_id` | `String` | Optional | The unique ID of the item variation purchased, if any. | + +### Example (as JSON) + +```json +{ + "category_name": null, + "sku": null, + "item_id": null, + "item_variation_id": null +} +``` + diff --git a/doc/models/v1-payment-itemization-itemization-type.md b/doc/models/v1-payment-itemization-itemization-type.md index 37f0741f..ac83d9fd 100644 --- a/doc/models/v1-payment-itemization-itemization-type.md +++ b/doc/models/v1-payment-itemization-itemization-type.md @@ -1,17 +1,17 @@ -## V1 Payment Itemization Itemization Type - -### Enumeration - -`V1PaymentItemizationItemizationType` - -### Fields - -| Name | Description | -| --- | --- | -| `ITEM` | - | -| `CUSTOM_AMOUNT` | - | -| `GIFT_CARD_ACTIVATION` | - | -| `GIFT_CARD_RELOAD` | - | -| `GIFT_CARD_UNKNOWN` | - | -| `OTHER` | - | - +## V1 Payment Itemization Itemization Type + +### Enumeration + +`V1PaymentItemizationItemizationType` + +### Fields + +| Name | Description | +| --- | --- | +| `ITEM` | - | +| `CUSTOM_AMOUNT` | - | +| `GIFT_CARD_ACTIVATION` | - | +| `GIFT_CARD_RELOAD` | - | +| `GIFT_CARD_UNKNOWN` | - | +| `OTHER` | - | + diff --git a/doc/models/v1-payment-itemization.md b/doc/models/v1-payment-itemization.md index b20e7614..a736f121 100644 --- a/doc/models/v1-payment-itemization.md +++ b/doc/models/v1-payment-itemization.md @@ -1,64 +1,64 @@ -## V1 Payment Itemization - -Payment include an` itemizations` field that lists the items purchased, -along with associated fees, modifiers, and discounts. Each itemization has an -`itemization_type` field that indicates which of the following the itemization -represents: - -
    -
  • An item variation from the merchant's item library
    • -
  • A custom monetary amount
    • -
  • -An action performed on a Square gift card, such as activating or -reloading it. -
    • -
- -*Note**: itemization information included in a `Payment` object reflects -details collected **at the time of the payment**. Details such as the name or -price of items might have changed since the payment was processed. - -### Structure - -`V1PaymentItemization` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The item's name. | -| `quantity` | `Float` | Optional | The quantity of the item purchased. This can be a decimal value. | -| `itemization_type` | [`String (V1 Payment Itemization Itemization Type)`](/doc/models/v1-payment-itemization-itemization-type.md) | Optional | - | -| `item_detail` | [`V1 Payment Item Detail Hash`](/doc/models/v1-payment-item-detail.md) | Optional | V1PaymentItemDetail | -| `notes` | `String` | Optional | Notes entered by the merchant about the item at the time of payment, if any. | -| `item_variation_name` | `String` | Optional | The name of the item variation purchased, if any. | -| `total_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `single_quantity_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `gross_sales_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `discount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `net_sales_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `taxes` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | All taxes applied to this itemization. | -| `discounts` | [`Array`](/doc/models/v1-payment-discount.md) | Optional | All discounts applied to this itemization. | -| `modifiers` | [`Array`](/doc/models/v1-payment-modifier.md) | Optional | All modifier options applied to this itemization. | - -### Example (as JSON) - -```json -{ - "name": null, - "quantity": null, - "itemization_type": null, - "item_detail": null, - "notes": null, - "item_variation_name": null, - "total_money": null, - "single_quantity_money": null, - "gross_sales_money": null, - "discount_money": null, - "net_sales_money": null, - "taxes": null, - "discounts": null, - "modifiers": null -} -``` - +## V1 Payment Itemization + +Payment include an` itemizations` field that lists the items purchased, +along with associated fees, modifiers, and discounts. Each itemization has an +`itemization_type` field that indicates which of the following the itemization +represents: + +
    +
  • An item variation from the merchant's item library
    • +
  • A custom monetary amount
    • +
  • +An action performed on a Square gift card, such as activating or +reloading it. +
    • +
+ +*Note**: itemization information included in a `Payment` object reflects +details collected **at the time of the payment**. Details such as the name or +price of items might have changed since the payment was processed. + +### Structure + +`V1PaymentItemization` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The item's name. | +| `quantity` | `Float` | Optional | The quantity of the item purchased. This can be a decimal value. | +| `itemization_type` | [`String (V1 Payment Itemization Itemization Type)`](/doc/models/v1-payment-itemization-itemization-type.md) | Optional | - | +| `item_detail` | [`V1 Payment Item Detail Hash`](/doc/models/v1-payment-item-detail.md) | Optional | V1PaymentItemDetail | +| `notes` | `String` | Optional | Notes entered by the merchant about the item at the time of payment, if any. | +| `item_variation_name` | `String` | Optional | The name of the item variation purchased, if any. | +| `total_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `single_quantity_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `gross_sales_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `discount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `net_sales_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `taxes` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | All taxes applied to this itemization. | +| `discounts` | [`Array`](/doc/models/v1-payment-discount.md) | Optional | All discounts applied to this itemization. | +| `modifiers` | [`Array`](/doc/models/v1-payment-modifier.md) | Optional | All modifier options applied to this itemization. | + +### Example (as JSON) + +```json +{ + "name": null, + "quantity": null, + "itemization_type": null, + "item_detail": null, + "notes": null, + "item_variation_name": null, + "total_money": null, + "single_quantity_money": null, + "gross_sales_money": null, + "discount_money": null, + "net_sales_money": null, + "taxes": null, + "discounts": null, + "modifiers": null +} +``` + diff --git a/doc/models/v1-payment-modifier.md b/doc/models/v1-payment-modifier.md index 759816c2..8df0f287 100644 --- a/doc/models/v1-payment-modifier.md +++ b/doc/models/v1-payment-modifier.md @@ -1,26 +1,26 @@ -## V1 Payment Modifier - -V1PaymentModifier - -### Structure - -`V1PaymentModifier` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The modifier option's name. | -| `applied_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `modifier_option_id` | `String` | Optional | TThe ID of the applied modifier option, if available. Modifier options applied in older versions of Square Register might not have an ID. | - -### Example (as JSON) - -```json -{ - "name": null, - "applied_money": null, - "modifier_option_id": null -} -``` - +## V1 Payment Modifier + +V1PaymentModifier + +### Structure + +`V1PaymentModifier` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The modifier option's name. | +| `applied_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `modifier_option_id` | `String` | Optional | TThe ID of the applied modifier option, if available. Modifier options applied in older versions of Square Register might not have an ID. | + +### Example (as JSON) + +```json +{ + "name": null, + "applied_money": null, + "modifier_option_id": null +} +``` + diff --git a/doc/models/v1-payment-surcharge-type.md b/doc/models/v1-payment-surcharge-type.md index b9af2561..866b9204 100644 --- a/doc/models/v1-payment-surcharge-type.md +++ b/doc/models/v1-payment-surcharge-type.md @@ -1,14 +1,14 @@ -## V1 Payment Surcharge Type - -### Enumeration - -`V1PaymentSurchargeType` - -### Fields - -| Name | Description | -| --- | --- | -| `UNKNOWN` | - | -| `AUTO_GRATUITY` | - | -| `CUSTOM` | - | - +## V1 Payment Surcharge Type + +### Enumeration + +`V1PaymentSurchargeType` + +### Fields + +| Name | Description | +| --- | --- | +| `UNKNOWN` | - | +| `AUTO_GRATUITY` | - | +| `CUSTOM` | - | + diff --git a/doc/models/v1-payment-surcharge.md b/doc/models/v1-payment-surcharge.md index 08e9168b..9bf13e23 100644 --- a/doc/models/v1-payment-surcharge.md +++ b/doc/models/v1-payment-surcharge.md @@ -1,36 +1,36 @@ -## V1 Payment Surcharge - -V1PaymentSurcharge - -### Structure - -`V1PaymentSurcharge` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The name of the surcharge. | -| `applied_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `rate` | `String` | Optional | The amount of the surcharge as a percentage. The percentage is provided as a string representing the decimal equivalent of the percentage. For example, "0.7" corresponds to a 7% surcharge. Exactly one of rate or amount_money should be set. | -| `amount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `type` | [`String (V1 Payment Surcharge Type)`](/doc/models/v1-payment-surcharge-type.md) | Optional | - | -| `taxable` | `Boolean` | Optional | Indicates whether the surcharge is taxable. | -| `taxes` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | The list of taxes that should be applied to the surcharge. | -| `surcharge_id` | `String` | Optional | A Square-issued unique identifier associated with the surcharge. | - -### Example (as JSON) - -```json -{ - "name": null, - "applied_money": null, - "rate": null, - "amount_money": null, - "type": null, - "taxable": null, - "taxes": null, - "surcharge_id": null -} -``` - +## V1 Payment Surcharge + +V1PaymentSurcharge + +### Structure + +`V1PaymentSurcharge` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The name of the surcharge. | +| `applied_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `rate` | `String` | Optional | The amount of the surcharge as a percentage. The percentage is provided as a string representing the decimal equivalent of the percentage. For example, "0.7" corresponds to a 7% surcharge. Exactly one of rate or amount_money should be set. | +| `amount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `type` | [`String (V1 Payment Surcharge Type)`](/doc/models/v1-payment-surcharge-type.md) | Optional | - | +| `taxable` | `Boolean` | Optional | Indicates whether the surcharge is taxable. | +| `taxes` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | The list of taxes that should be applied to the surcharge. | +| `surcharge_id` | `String` | Optional | A Square-issued unique identifier associated with the surcharge. | + +### Example (as JSON) + +```json +{ + "name": null, + "applied_money": null, + "rate": null, + "amount_money": null, + "type": null, + "taxable": null, + "taxes": null, + "surcharge_id": null +} +``` + diff --git a/doc/models/v1-payment-tax.md b/doc/models/v1-payment-tax.md index 401c60c2..f3e21dee 100644 --- a/doc/models/v1-payment-tax.md +++ b/doc/models/v1-payment-tax.md @@ -1,32 +1,32 @@ -## V1 Payment Tax - -V1PaymentTax - -### Structure - -`V1PaymentTax` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `name` | `String` | Optional | The merchant-defined name of the tax. | -| `applied_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `rate` | `String` | Optional | The rate of the tax, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%. | -| `inclusion_type` | [`String (V1 Fee Inclusion Type)`](/doc/models/v1-fee-inclusion-type.md) | Optional | - | -| `fee_id` | `String` | Optional | The ID of the tax, if available. Taxes applied in older versions of Square Register might not have an ID. | - -### Example (as JSON) - -```json -{ - "errors": null, - "name": null, - "applied_money": null, - "rate": null, - "inclusion_type": null, - "fee_id": null -} -``` - +## V1 Payment Tax + +V1PaymentTax + +### Structure + +`V1PaymentTax` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `name` | `String` | Optional | The merchant-defined name of the tax. | +| `applied_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `rate` | `String` | Optional | The rate of the tax, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%. | +| `inclusion_type` | [`String (V1 Fee Inclusion Type)`](/doc/models/v1-fee-inclusion-type.md) | Optional | - | +| `fee_id` | `String` | Optional | The ID of the tax, if available. Taxes applied in older versions of Square Register might not have an ID. | + +### Example (as JSON) + +```json +{ + "errors": null, + "name": null, + "applied_money": null, + "rate": null, + "inclusion_type": null, + "fee_id": null +} +``` + diff --git a/doc/models/v1-payment.md b/doc/models/v1-payment.md index 4be6fe4d..e7ef8dda 100644 --- a/doc/models/v1-payment.md +++ b/doc/models/v1-payment.md @@ -1,92 +1,92 @@ -## V1 Payment - -A payment represents a paid transaction between a Square merchant and a -customer. Payment details are usually available from Connect API endpoints -within a few minutes after the transaction completes. - -Each Payment object includes several fields that end in `_money`. These fields -describe the various amounts of money that contribute to the payment total: - -
    -
  • -Monetary values are positive if they represent an -increase in the amount of money the merchant receives (e.g., -tax_money, tip_money). -
    • -
  • -Monetary values are negative if they represent an -decrease in the amount of money the merchant receives (e.g., -discount_money, refunded_money). -
    • -
- -### Structure - -`V1Payment` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The payment's unique identifier. | -| `merchant_id` | `String` | Optional | The unique identifier of the merchant that took the payment. | -| `created_at` | `String` | Optional | The time when the payment was created, in ISO 8601 format. Reflects the time of the first payment if the object represents an incomplete partial payment, and the time of the last or complete payment otherwise. | -| `creator_id` | `String` | Optional | The unique identifier of the Square account that took the payment. | -| `device` | [`Device Hash`](/doc/models/device.md) | Optional | - | -| `payment_url` | `String` | Optional | The URL of the payment's detail page in the merchant dashboard. The merchant must be signed in to the merchant dashboard to view this page. | -| `receipt_url` | `String` | Optional | The URL of the receipt for the payment. Note that for split tender
payments, this URL corresponds to the receipt for the first tender
listed in the payment's tender field. Each Tender object has its own
receipt_url field you can use to get the other receipts associated with
a split tender payment. | -| `inclusive_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `additive_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `tip_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `discount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `total_collected_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `processing_fee_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `net_total_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `refunded_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `swedish_rounding_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `gross_sales_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `net_sales_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `inclusive_tax` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | All of the inclusive taxes associated with the payment. | -| `additive_tax` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | All of the additive taxes associated with the payment. | -| `tender` | [`Array`](/doc/models/v1-tender.md) | Optional | All of the tenders associated with the payment. | -| `refunds` | [`Array`](/doc/models/v1-refund.md) | Optional | All of the refunds applied to the payment. Note that the value of all refunds on a payment can exceed the value of all tenders if a merchant chooses to refund money to a tender after previously accepting returned goods as part of an exchange. | -| `itemizations` | [`Array`](/doc/models/v1-payment-itemization.md) | Optional | The items purchased in the payment. | -| `surcharge_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `surcharges` | [`Array`](/doc/models/v1-payment-surcharge.md) | Optional | A list of all surcharges associated with the payment. | -| `is_partial` | `Boolean` | Optional | Indicates whether or not the payment is only partially paid for.
If true, this payment will have the tenders collected so far, but the
itemizations will be empty until the payment is completed. | - -### Example (as JSON) - -```json -{ - "id": null, - "merchant_id": null, - "created_at": null, - "creator_id": null, - "device": null, - "payment_url": null, - "receipt_url": null, - "inclusive_tax_money": null, - "additive_tax_money": null, - "tax_money": null, - "tip_money": null, - "discount_money": null, - "total_collected_money": null, - "processing_fee_money": null, - "net_total_money": null, - "refunded_money": null, - "swedish_rounding_money": null, - "gross_sales_money": null, - "net_sales_money": null, - "inclusive_tax": null, - "additive_tax": null, - "tender": null, - "refunds": null, - "itemizations": null, - "surcharge_money": null, - "surcharges": null, - "is_partial": null -} -``` - +## V1 Payment + +A payment represents a paid transaction between a Square merchant and a +customer. Payment details are usually available from Connect API endpoints +within a few minutes after the transaction completes. + +Each Payment object includes several fields that end in `_money`. These fields +describe the various amounts of money that contribute to the payment total: + +
    +
  • +Monetary values are positive if they represent an +increase in the amount of money the merchant receives (e.g., +tax_money, tip_money). +
    • +
  • +Monetary values are negative if they represent an +decrease in the amount of money the merchant receives (e.g., +discount_money, refunded_money). +
    • +
+ +### Structure + +`V1Payment` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The payment's unique identifier. | +| `merchant_id` | `String` | Optional | The unique identifier of the merchant that took the payment. | +| `created_at` | `String` | Optional | The time when the payment was created, in ISO 8601 format. Reflects the time of the first payment if the object represents an incomplete partial payment, and the time of the last or complete payment otherwise. | +| `creator_id` | `String` | Optional | The unique identifier of the Square account that took the payment. | +| `device` | [`Device Hash`](/doc/models/device.md) | Optional | - | +| `payment_url` | `String` | Optional | The URL of the payment's detail page in the merchant dashboard. The merchant must be signed in to the merchant dashboard to view this page. | +| `receipt_url` | `String` | Optional | The URL of the receipt for the payment. Note that for split tender
payments, this URL corresponds to the receipt for the first tender
listed in the payment's tender field. Each Tender object has its own
receipt_url field you can use to get the other receipts associated with
a split tender payment. | +| `inclusive_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `additive_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `tip_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `discount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `total_collected_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `processing_fee_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `net_total_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `refunded_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `swedish_rounding_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `gross_sales_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `net_sales_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `inclusive_tax` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | All of the inclusive taxes associated with the payment. | +| `additive_tax` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | All of the additive taxes associated with the payment. | +| `tender` | [`Array`](/doc/models/v1-tender.md) | Optional | All of the tenders associated with the payment. | +| `refunds` | [`Array`](/doc/models/v1-refund.md) | Optional | All of the refunds applied to the payment. Note that the value of all refunds on a payment can exceed the value of all tenders if a merchant chooses to refund money to a tender after previously accepting returned goods as part of an exchange. | +| `itemizations` | [`Array`](/doc/models/v1-payment-itemization.md) | Optional | The items purchased in the payment. | +| `surcharge_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `surcharges` | [`Array`](/doc/models/v1-payment-surcharge.md) | Optional | A list of all surcharges associated with the payment. | +| `is_partial` | `Boolean` | Optional | Indicates whether or not the payment is only partially paid for.
If true, this payment will have the tenders collected so far, but the
itemizations will be empty until the payment is completed. | + +### Example (as JSON) + +```json +{ + "id": null, + "merchant_id": null, + "created_at": null, + "creator_id": null, + "device": null, + "payment_url": null, + "receipt_url": null, + "inclusive_tax_money": null, + "additive_tax_money": null, + "tax_money": null, + "tip_money": null, + "discount_money": null, + "total_collected_money": null, + "processing_fee_money": null, + "net_total_money": null, + "refunded_money": null, + "swedish_rounding_money": null, + "gross_sales_money": null, + "net_sales_money": null, + "inclusive_tax": null, + "additive_tax": null, + "tender": null, + "refunds": null, + "itemizations": null, + "surcharge_money": null, + "surcharges": null, + "is_partial": null +} +``` + diff --git a/doc/models/v1-phone-number.md b/doc/models/v1-phone-number.md index 0997f911..96389545 100644 --- a/doc/models/v1-phone-number.md +++ b/doc/models/v1-phone-number.md @@ -1,24 +1,24 @@ -## V1 Phone Number - -Represents a phone number. - -### Structure - -`V1PhoneNumber` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `calling_code` | `String` | The phone number's international calling code. For US phone numbers, this value is +1. | -| `number` | `String` | The phone number. | - -### Example (as JSON) - -```json -{ - "calling_code": "calling_code4", - "number": "number2" -} -``` - +## V1 Phone Number + +Represents a phone number. + +### Structure + +`V1PhoneNumber` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `calling_code` | `String` | The phone number's international calling code. For US phone numbers, this value is +1. | +| `number` | `String` | The phone number. | + +### Example (as JSON) + +```json +{ + "calling_code": "calling_code4", + "number": "number2" +} +``` + diff --git a/doc/models/v1-refund.md b/doc/models/v1-refund.md index 06d0e2ee..0b769a99 100644 --- a/doc/models/v1-refund.md +++ b/doc/models/v1-refund.md @@ -1,56 +1,56 @@ -## V1 Refund - -V1Refund - -### Structure - -`V1Refund` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `type` | [`String (V1 Create Refund Request Type)`](/doc/models/v1-create-refund-request-type.md) | Optional | - | -| `reason` | `String` | Optional | The merchant-specified reason for the refund. | -| `refunded_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `refunded_processing_fee_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `refunded_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `refunded_additive_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `refunded_additive_tax` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | All of the additive taxes associated with the refund. | -| `refunded_inclusive_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `refunded_inclusive_tax` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | All of the inclusive taxes associated with the refund. | -| `refunded_tip_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `refunded_discount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `refunded_surcharge_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `refunded_surcharges` | [`Array`](/doc/models/v1-payment-surcharge.md) | Optional | A list of all surcharges associated with the refund. | -| `created_at` | `String` | Optional | The time when the merchant initiated the refund for Square to process, in ISO 8601 format. | -| `processed_at` | `String` | Optional | The time when Square processed the refund on behalf of the merchant, in ISO 8601 format. | -| `payment_id` | `String` | Optional | A Square-issued ID associated with the refund. For single-tender refunds, payment_id is the ID of the original payment ID. For split-tender refunds, payment_id is the ID of the original tender. For exchange-based refunds (is_exchange == true), payment_id is the ID of the original payment ID even if the payment includes other tenders. | -| `merchant_id` | `String` | Optional | - | -| `is_exchange` | `Boolean` | Optional | Indicates whether or not the refund is associated with an exchange. If is_exchange is true, the refund reflects the value of goods returned in the exchange not the total money refunded. | - -### Example (as JSON) - -```json -{ - "type": null, - "reason": null, - "refunded_money": null, - "refunded_processing_fee_money": null, - "refunded_tax_money": null, - "refunded_additive_tax_money": null, - "refunded_additive_tax": null, - "refunded_inclusive_tax_money": null, - "refunded_inclusive_tax": null, - "refunded_tip_money": null, - "refunded_discount_money": null, - "refunded_surcharge_money": null, - "refunded_surcharges": null, - "created_at": null, - "processed_at": null, - "payment_id": null, - "merchant_id": null, - "is_exchange": null -} -``` - +## V1 Refund + +V1Refund + +### Structure + +`V1Refund` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `type` | [`String (V1 Create Refund Request Type)`](/doc/models/v1-create-refund-request-type.md) | Optional | - | +| `reason` | `String` | Optional | The merchant-specified reason for the refund. | +| `refunded_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `refunded_processing_fee_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `refunded_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `refunded_additive_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `refunded_additive_tax` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | All of the additive taxes associated with the refund. | +| `refunded_inclusive_tax_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `refunded_inclusive_tax` | [`Array`](/doc/models/v1-payment-tax.md) | Optional | All of the inclusive taxes associated with the refund. | +| `refunded_tip_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `refunded_discount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `refunded_surcharge_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `refunded_surcharges` | [`Array`](/doc/models/v1-payment-surcharge.md) | Optional | A list of all surcharges associated with the refund. | +| `created_at` | `String` | Optional | The time when the merchant initiated the refund for Square to process, in ISO 8601 format. | +| `processed_at` | `String` | Optional | The time when Square processed the refund on behalf of the merchant, in ISO 8601 format. | +| `payment_id` | `String` | Optional | A Square-issued ID associated with the refund. For single-tender refunds, payment_id is the ID of the original payment ID. For split-tender refunds, payment_id is the ID of the original tender. For exchange-based refunds (is_exchange == true), payment_id is the ID of the original payment ID even if the payment includes other tenders. | +| `merchant_id` | `String` | Optional | - | +| `is_exchange` | `Boolean` | Optional | Indicates whether or not the refund is associated with an exchange. If is_exchange is true, the refund reflects the value of goods returned in the exchange not the total money refunded. | + +### Example (as JSON) + +```json +{ + "type": null, + "reason": null, + "refunded_money": null, + "refunded_processing_fee_money": null, + "refunded_tax_money": null, + "refunded_additive_tax_money": null, + "refunded_additive_tax": null, + "refunded_inclusive_tax_money": null, + "refunded_inclusive_tax": null, + "refunded_tip_money": null, + "refunded_discount_money": null, + "refunded_surcharge_money": null, + "refunded_surcharges": null, + "created_at": null, + "processed_at": null, + "payment_id": null, + "merchant_id": null, + "is_exchange": null +} +``` + diff --git a/doc/models/v1-settlement-entry-type.md b/doc/models/v1-settlement-entry-type.md index 838cab42..f629efb2 100644 --- a/doc/models/v1-settlement-entry-type.md +++ b/doc/models/v1-settlement-entry-type.md @@ -1,32 +1,32 @@ -## V1 Settlement Entry Type - -### Enumeration - -`V1SettlementEntryType` - -### Fields - -| Name | Description | -| --- | --- | -| `ADJUSTMENT` | A manual adjustment applied to the merchant's account by Square | -| `BALANCE_CHARGE` | A payment from an existing Square balance, such as a gift card | -| `CHARGE` | A credit card payment CAPTURE | -| `FREE_PROCESSING` | Square offers Free Payments Processing for a variety of business scenarios including seller referral or when we want to apologize for a bug, customer service, repricing complication, etc. This entry represents a credit to the merchant for the purposes of Free Processing. | -| `HOLD_ADJUSTMENT` | An adjustment made by Square related to holding/releasing a payment | -| `PAID_SERVICE_FEE` | a fee paid to a 3rd party merchant | -| `PAID_SERVICE_FEE_REFUND` | a refund for a 3rd party merchant fee | -| `REDEMPTION_CODE` | Repayment for a redemption code | -| `REFUND` | A refund for an existing card payment | -| `RETURNED_PAYOUT` | An entry created when we receive a response for the ACH file we sent indicating that the settlement of the original entry failed. | -| `SQUARE_CAPITAL_ADVANCE` | Initial deposit to a merchant for a Capital merchant cash advance (MCA). | -| `SQUARE_CAPITAL_PAYMENT` | Capital merchant cash advance (MCA) assessment. These are, generally, proportional to the merchant's sales but may be issued for other reasons related to the MCA. | -| `SQUARE_CAPITAL_REVERSED_PAYMENT` | Capital merchant cash advance (MCA) assessment refund. These are, generally, proportional to the merchant's refunds but may be issued for other reasons related to the MCA. | -| `SUBSCRIPTION_FEE` | Fee charged for subscription to a Square product | -| `SUBSCRIPTION_FEE_REFUND` | Refund of a previously charged Square product subscription fee. | -| `OTHER` | - | -| `INCENTED_PAYMENT` | A payment in which Square covers part of the funds for a purchase | -| `RETURNED_ACH_ENTRY` | A settlement failed to be processed and the settlement amount has been returned to the account | -| `RETURNED_SQUARE_275` | Refund for cancelling a Square Plus subscription | -| `SQUARE_275` | Fee charged for a Square Plus subscription ($275) | -| `SQUARE_CARD` | Settlements to or withdrawals from the Square Card (an asset) | - +## V1 Settlement Entry Type + +### Enumeration + +`V1SettlementEntryType` + +### Fields + +| Name | Description | +| --- | --- | +| `ADJUSTMENT` | A manual adjustment applied to the merchant's account by Square | +| `BALANCE_CHARGE` | A payment from an existing Square balance, such as a gift card | +| `CHARGE` | A credit card payment CAPTURE | +| `FREE_PROCESSING` | Square offers Free Payments Processing for a variety of business scenarios including seller referral or when we want to apologize for a bug, customer service, repricing complication, etc. This entry represents a credit to the merchant for the purposes of Free Processing. | +| `HOLD_ADJUSTMENT` | An adjustment made by Square related to holding/releasing a payment | +| `PAID_SERVICE_FEE` | a fee paid to a 3rd party merchant | +| `PAID_SERVICE_FEE_REFUND` | a refund for a 3rd party merchant fee | +| `REDEMPTION_CODE` | Repayment for a redemption code | +| `REFUND` | A refund for an existing card payment | +| `RETURNED_PAYOUT` | An entry created when we receive a response for the ACH file we sent indicating that the settlement of the original entry failed. | +| `SQUARE_CAPITAL_ADVANCE` | Initial deposit to a merchant for a Capital merchant cash advance (MCA). | +| `SQUARE_CAPITAL_PAYMENT` | Capital merchant cash advance (MCA) assessment. These are, generally, proportional to the merchant's sales but may be issued for other reasons related to the MCA. | +| `SQUARE_CAPITAL_REVERSED_PAYMENT` | Capital merchant cash advance (MCA) assessment refund. These are, generally, proportional to the merchant's refunds but may be issued for other reasons related to the MCA. | +| `SUBSCRIPTION_FEE` | Fee charged for subscription to a Square product | +| `SUBSCRIPTION_FEE_REFUND` | Refund of a previously charged Square product subscription fee. | +| `OTHER` | - | +| `INCENTED_PAYMENT` | A payment in which Square covers part of the funds for a purchase | +| `RETURNED_ACH_ENTRY` | A settlement failed to be processed and the settlement amount has been returned to the account | +| `RETURNED_SQUARE_275` | Refund for cancelling a Square Plus subscription | +| `SQUARE_275` | Fee charged for a Square Plus subscription ($275) | +| `SQUARE_CARD` | Settlements to or withdrawals from the Square Card (an asset) | + diff --git a/doc/models/v1-settlement-entry.md b/doc/models/v1-settlement-entry.md index 9d77ca9d..1948b212 100644 --- a/doc/models/v1-settlement-entry.md +++ b/doc/models/v1-settlement-entry.md @@ -1,28 +1,28 @@ -## V1 Settlement Entry - -V1SettlementEntry - -### Structure - -`V1SettlementEntry` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `payment_id` | `String` | Optional | The settlement's unique identifier. | -| `type` | [`String (V1 Settlement Entry Type)`](/doc/models/v1-settlement-entry-type.md) | Optional | - | -| `amount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `fee_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "payment_id": null, - "type": null, - "amount_money": null, - "fee_money": null -} -``` - +## V1 Settlement Entry + +V1SettlementEntry + +### Structure + +`V1SettlementEntry` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `payment_id` | `String` | Optional | The settlement's unique identifier. | +| `type` | [`String (V1 Settlement Entry Type)`](/doc/models/v1-settlement-entry-type.md) | Optional | - | +| `amount_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `fee_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "payment_id": null, + "type": null, + "amount_money": null, + "fee_money": null +} +``` + diff --git a/doc/models/v1-settlement.md b/doc/models/v1-settlement.md index c7596cbf..1f4c5584 100644 --- a/doc/models/v1-settlement.md +++ b/doc/models/v1-settlement.md @@ -1,32 +1,32 @@ -## V1 Settlement - -V1Settlement - -### Structure - -`V1Settlement` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The settlement's unique identifier. | -| `status` | [`String (V1 List Settlements Request Status)`](/doc/models/v1-list-settlements-request-status.md) | Optional | - | -| `total_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `initiated_at` | `String` | Optional | The time when the settlement was submitted for deposit or withdrawal, in ISO 8601 format. | -| `bank_account_id` | `String` | Optional | The Square-issued unique identifier for the bank account associated with the settlement. | -| `entries` | [`Array`](/doc/models/v1-settlement-entry.md) | Optional | The entries included in this settlement. | - -### Example (as JSON) - -```json -{ - "id": null, - "status": null, - "total_money": null, - "initiated_at": null, - "bank_account_id": null, - "entries": null -} -``` - +## V1 Settlement + +V1Settlement + +### Structure + +`V1Settlement` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The settlement's unique identifier. | +| `status` | [`String (V1 List Settlements Request Status)`](/doc/models/v1-list-settlements-request-status.md) | Optional | - | +| `total_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `initiated_at` | `String` | Optional | The time when the settlement was submitted for deposit or withdrawal, in ISO 8601 format. | +| `bank_account_id` | `String` | Optional | The Square-issued unique identifier for the bank account associated with the settlement. | +| `entries` | [`Array`](/doc/models/v1-settlement-entry.md) | Optional | The entries included in this settlement. | + +### Example (as JSON) + +```json +{ + "id": null, + "status": null, + "total_money": null, + "initiated_at": null, + "bank_account_id": null, + "entries": null +} +``` + diff --git a/doc/models/v1-tender-card-brand.md b/doc/models/v1-tender-card-brand.md index 3194786b..5c5e3955 100644 --- a/doc/models/v1-tender-card-brand.md +++ b/doc/models/v1-tender-card-brand.md @@ -1,22 +1,22 @@ -## V1 Tender Card Brand - -The brand of a credit card. - -### Enumeration - -`V1TenderCardBrand` - -### Fields - -| Name | Description | -| --- | --- | -| `OTHER_BRAND` | - | -| `VISA` | - | -| `MASTER_CARD` | - | -| `AMERICAN_EXPRESS` | - | -| `DISCOVER` | - | -| `DISCOVER_DINERS` | - | -| `JCB` | - | -| `CHINA_UNIONPAY` | - | -| `SQUARE_GIFT_CARD` | - | - +## V1 Tender Card Brand + +The brand of a credit card. + +### Enumeration + +`V1TenderCardBrand` + +### Fields + +| Name | Description | +| --- | --- | +| `OTHER_BRAND` | - | +| `VISA` | - | +| `MASTER_CARD` | - | +| `AMERICAN_EXPRESS` | - | +| `DISCOVER` | - | +| `DISCOVER_DINERS` | - | +| `JCB` | - | +| `CHINA_UNIONPAY` | - | +| `SQUARE_GIFT_CARD` | - | + diff --git a/doc/models/v1-tender-entry-method.md b/doc/models/v1-tender-entry-method.md index e4469b0e..54624918 100644 --- a/doc/models/v1-tender-entry-method.md +++ b/doc/models/v1-tender-entry-method.md @@ -1,18 +1,18 @@ -## V1 Tender Entry Method - -### Enumeration - -`V1TenderEntryMethod` - -### Fields - -| Name | Description | -| --- | --- | -| `MANUAL` | - | -| `SCANNED` | - | -| `SQUARE_CASH` | - | -| `SQUARE_WALLET` | - | -| `SWIPED` | - | -| `WEB_FORM` | - | -| `OTHER` | - | - +## V1 Tender Entry Method + +### Enumeration + +`V1TenderEntryMethod` + +### Fields + +| Name | Description | +| --- | --- | +| `MANUAL` | - | +| `SCANNED` | - | +| `SQUARE_CASH` | - | +| `SQUARE_WALLET` | - | +| `SWIPED` | - | +| `WEB_FORM` | - | +| `OTHER` | - | + diff --git a/doc/models/v1-tender-type.md b/doc/models/v1-tender-type.md index a7d07f04..f7de99b8 100644 --- a/doc/models/v1-tender-type.md +++ b/doc/models/v1-tender-type.md @@ -1,19 +1,19 @@ -## V1 Tender Type - -### Enumeration - -`V1TenderType` - -### Fields - -| Name | Description | -| --- | --- | -| `CREDIT_CARD` | - | -| `CASH` | - | -| `THIRD_PARTY_CARD` | - | -| `NO_SALE` | - | -| `SQUARE_WALLET` | - | -| `SQUARE_GIFT_CARD` | - | -| `UNKNOWN` | - | -| `OTHER` | - | - +## V1 Tender Type + +### Enumeration + +`V1TenderType` + +### Fields + +| Name | Description | +| --- | --- | +| `CREDIT_CARD` | - | +| `CASH` | - | +| `THIRD_PARTY_CARD` | - | +| `NO_SALE` | - | +| `SQUARE_WALLET` | - | +| `SQUARE_GIFT_CARD` | - | +| `UNKNOWN` | - | +| `OTHER` | - | + diff --git a/doc/models/v1-tender.md b/doc/models/v1-tender.md index ac37344c..237675dc 100644 --- a/doc/models/v1-tender.md +++ b/doc/models/v1-tender.md @@ -1,73 +1,73 @@ -## V1 Tender - -A tender represents a discrete monetary exchange. Square represents this -exchange as a money object with a specific currency and amount, where the -amount is given in the smallest denomination of the given currency. - -Square POS can accept more than one form of tender for a single payment (such -as by splitting a bill between a credit card and a gift card). The `tender` -field of the Payment object lists all forms of tender used for the payment. - -Split tender payments behave slightly differently from single tender payments: - -The receipt_url for a split tender corresponds only to the first tender listed -in the tender field. To get the receipt URLs for the remaining tenders, use -the receipt_url fields of the corresponding Tender objects. - -*A note on gift cards**: when a customer purchases a Square gift card from a -merchant, the merchant receives the full amount of the gift card in the -associated payment. - -When that gift card is used as a tender, the balance of the gift card is -reduced and the merchant receives no funds. A `Tender` object with a type of -`SQUARE_GIFT_CARD` indicates a gift card was used for some or all of the -associated payment. - -### Structure - -`V1Tender` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The tender's unique ID. | -| `type` | [`String (V1 Tender Type)`](/doc/models/v1-tender-type.md) | Optional | - | -| `name` | `String` | Optional | A human-readable description of the tender. | -| `employee_id` | `String` | Optional | The ID of the employee that processed the tender. | -| `receipt_url` | `String` | Optional | The URL of the receipt for the tender. | -| `card_brand` | [`String (V1 Tender Card Brand)`](/doc/models/v1-tender-card-brand.md) | Optional | The brand of a credit card. | -| `pan_suffix` | `String` | Optional | The last four digits of the provided credit card's account number. | -| `entry_method` | [`String (V1 Tender Entry Method)`](/doc/models/v1-tender-entry-method.md) | Optional | - | -| `payment_note` | `String` | Optional | Notes entered by the merchant about the tender at the time of payment, if any. Typically only present for tender with the type: OTHER. | -| `total_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `tendered_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `tendered_at` | `String` | Optional | The time when the tender was created, in ISO 8601 format. | -| `settled_at` | `String` | Optional | The time when the tender was settled, in ISO 8601 format. | -| `change_back_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `refunded_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `is_exchange` | `Boolean` | Optional | Indicates whether or not the tender is associated with an exchange. If is_exchange is true, the tender represents the value of goods returned in an exchange not the actual money paid. The exchange value reduces the tender amounts needed to pay for items purchased in the exchange. | - -### Example (as JSON) - -```json -{ - "id": null, - "type": null, - "name": null, - "employee_id": null, - "receipt_url": null, - "card_brand": null, - "pan_suffix": null, - "entry_method": null, - "payment_note": null, - "total_money": null, - "tendered_money": null, - "tendered_at": null, - "settled_at": null, - "change_back_money": null, - "refunded_money": null, - "is_exchange": null -} -``` - +## V1 Tender + +A tender represents a discrete monetary exchange. Square represents this +exchange as a money object with a specific currency and amount, where the +amount is given in the smallest denomination of the given currency. + +Square POS can accept more than one form of tender for a single payment (such +as by splitting a bill between a credit card and a gift card). The `tender` +field of the Payment object lists all forms of tender used for the payment. + +Split tender payments behave slightly differently from single tender payments: + +The receipt_url for a split tender corresponds only to the first tender listed +in the tender field. To get the receipt URLs for the remaining tenders, use +the receipt_url fields of the corresponding Tender objects. + +*A note on gift cards**: when a customer purchases a Square gift card from a +merchant, the merchant receives the full amount of the gift card in the +associated payment. + +When that gift card is used as a tender, the balance of the gift card is +reduced and the merchant receives no funds. A `Tender` object with a type of +`SQUARE_GIFT_CARD` indicates a gift card was used for some or all of the +associated payment. + +### Structure + +`V1Tender` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The tender's unique ID. | +| `type` | [`String (V1 Tender Type)`](/doc/models/v1-tender-type.md) | Optional | - | +| `name` | `String` | Optional | A human-readable description of the tender. | +| `employee_id` | `String` | Optional | The ID of the employee that processed the tender. | +| `receipt_url` | `String` | Optional | The URL of the receipt for the tender. | +| `card_brand` | [`String (V1 Tender Card Brand)`](/doc/models/v1-tender-card-brand.md) | Optional | The brand of a credit card. | +| `pan_suffix` | `String` | Optional | The last four digits of the provided credit card's account number. | +| `entry_method` | [`String (V1 Tender Entry Method)`](/doc/models/v1-tender-entry-method.md) | Optional | - | +| `payment_note` | `String` | Optional | Notes entered by the merchant about the tender at the time of payment, if any. Typically only present for tender with the type: OTHER. | +| `total_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `tendered_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `tendered_at` | `String` | Optional | The time when the tender was created, in ISO 8601 format. | +| `settled_at` | `String` | Optional | The time when the tender was settled, in ISO 8601 format. | +| `change_back_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `refunded_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `is_exchange` | `Boolean` | Optional | Indicates whether or not the tender is associated with an exchange. If is_exchange is true, the tender represents the value of goods returned in an exchange not the actual money paid. The exchange value reduces the tender amounts needed to pay for items purchased in the exchange. | + +### Example (as JSON) + +```json +{ + "id": null, + "type": null, + "name": null, + "employee_id": null, + "receipt_url": null, + "card_brand": null, + "pan_suffix": null, + "entry_method": null, + "payment_note": null, + "total_money": null, + "tendered_money": null, + "tendered_at": null, + "settled_at": null, + "change_back_money": null, + "refunded_money": null, + "is_exchange": null +} +``` + diff --git a/doc/models/v1-timecard-event-event-type.md b/doc/models/v1-timecard-event-event-type.md index 420a4d8f..06c3d8a9 100644 --- a/doc/models/v1-timecard-event-event-type.md +++ b/doc/models/v1-timecard-event-event-type.md @@ -1,23 +1,23 @@ -## V1 Timecard Event Event Type - +## V1 Timecard Event Event Type + Actions that resulted in a change to a timecard. All timecard events created with the Connect API have an event type that begins with -`API`. - -### Enumeration - -`V1TimecardEventEventType` - -### Fields - -| Name | Description | -| --- | --- | -| `API_CREATE` | The timecard was created by a request to the
[CreateTimecard](#endpoint-v1employees-createtimecard) endpoint. | -| `API_EDIT` | The timecard was edited by a request to the
[UpdateTimecard](#endpoint-v1employees-updatetimecard) endpoint. | -| `API_DELETE` | The timecard was deleted by a request to the
[DeleteTimecard](#endpoint-v1employees-deletetimecard) endpoint. | -| `REGISTER_CLOCKIN` | The employee clocked in via Square Point of Sale. | -| `REGISTER_CLOCKOUT` | The employee clocked out via Square Point of Sale. | -| `DASHBOARD_SUPERVISOR_CLOSE` | A supervisor clocked out the employee from the merchant
dashboard. | -| `DASHBOARD_EDIT` | A supervisor manually edited the timecard from the merchant
dashboard | -| `DASHBOARD_DELETE` | A supervisor deleted the timecard from the merchant dashboard. | - +`API`. + +### Enumeration + +`V1TimecardEventEventType` + +### Fields + +| Name | Description | +| --- | --- | +| `API_CREATE` | The timecard was created by a request to the
[CreateTimecard](#endpoint-v1employees-createtimecard) endpoint. | +| `API_EDIT` | The timecard was edited by a request to the
[UpdateTimecard](#endpoint-v1employees-updatetimecard) endpoint. | +| `API_DELETE` | The timecard was deleted by a request to the
[DeleteTimecard](#endpoint-v1employees-deletetimecard) endpoint. | +| `REGISTER_CLOCKIN` | The employee clocked in via Square Point of Sale. | +| `REGISTER_CLOCKOUT` | The employee clocked out via Square Point of Sale. | +| `DASHBOARD_SUPERVISOR_CLOSE` | A supervisor clocked out the employee from the merchant
dashboard. | +| `DASHBOARD_EDIT` | A supervisor manually edited the timecard from the merchant
dashboard | +| `DASHBOARD_DELETE` | A supervisor deleted the timecard from the merchant dashboard. | + diff --git a/doc/models/v1-timecard-event.md b/doc/models/v1-timecard-event.md index 4560a74c..b56f1c26 100644 --- a/doc/models/v1-timecard-event.md +++ b/doc/models/v1-timecard-event.md @@ -1,30 +1,30 @@ -## V1 Timecard Event - -V1TimecardEvent - -### Structure - -`V1TimecardEvent` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The event's unique ID. | -| `event_type` | [`String (V1 Timecard Event Event Type)`](/doc/models/v1-timecard-event-event-type.md) | Optional | Actions that resulted in a change to a timecard. All timecard
events created with the Connect API have an event type that begins with
`API`. | -| `clockin_time` | `String` | Optional | The time the employee clocked in, in ISO 8601 format. | -| `clockout_time` | `String` | Optional | The time the employee clocked out, in ISO 8601 format. | -| `created_at` | `String` | Optional | The time when the event was created, in ISO 8601 format. | - -### Example (as JSON) - -```json -{ - "id": null, - "event_type": null, - "clockin_time": null, - "clockout_time": null, - "created_at": null -} -``` - +## V1 Timecard Event + +V1TimecardEvent + +### Structure + +`V1TimecardEvent` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The event's unique ID. | +| `event_type` | [`String (V1 Timecard Event Event Type)`](/doc/models/v1-timecard-event-event-type.md) | Optional | Actions that resulted in a change to a timecard. All timecard
events created with the Connect API have an event type that begins with
`API`. | +| `clockin_time` | `String` | Optional | The time the employee clocked in, in ISO 8601 format. | +| `clockout_time` | `String` | Optional | The time the employee clocked out, in ISO 8601 format. | +| `created_at` | `String` | Optional | The time when the event was created, in ISO 8601 format. | + +### Example (as JSON) + +```json +{ + "id": null, + "event_type": null, + "clockin_time": null, + "clockout_time": null, + "created_at": null +} +``` + diff --git a/doc/models/v1-timecard.md b/doc/models/v1-timecard.md index 9ea6e92c..6a934bf0 100644 --- a/doc/models/v1-timecard.md +++ b/doc/models/v1-timecard.md @@ -1,44 +1,44 @@ -## V1 Timecard - -Represents a timecard for an employee. - -### Structure - -`V1Timecard` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The timecard's unique ID. | -| `employee_id` | `String` | | The ID of the employee the timecard is associated with. | -| `deleted` | `Boolean` | Optional | If true, the timecard was deleted by the merchant, and it is no longer valid. | -| `clockin_time` | `String` | Optional | The clock-in time for the timecard, in ISO 8601 format. | -| `clockout_time` | `String` | Optional | The clock-out time for the timecard, in ISO 8601 format. Provide this value only if importing timecard information from another system. | -| `clockin_location_id` | `String` | Optional | The ID of the location the employee clocked in from. We strongly reccomend providing a clockin_location_id. Square uses the clockin_location_id to determine a timecard’s timezone and overtime rules. | -| `clockout_location_id` | `String` | Optional | The ID of the location the employee clocked out from. Provide this value only if importing timecard information from another system. | -| `created_at` | `String` | Optional | The time when the timecard was created, in ISO 8601 format. | -| `updated_at` | `String` | Optional | The time when the timecard was most recently updated, in ISO 8601 format. | -| `regular_seconds_worked` | `Float` | Optional | The total number of regular (non-overtime) seconds worked in the timecard. | -| `overtime_seconds_worked` | `Float` | Optional | The total number of overtime seconds worked in the timecard. | -| `doubletime_seconds_worked` | `Float` | Optional | The total number of doubletime seconds worked in the timecard. | - -### Example (as JSON) - -```json -{ - "id": null, - "employee_id": "employee_id0", - "deleted": null, - "clockin_time": null, - "clockout_time": null, - "clockin_location_id": null, - "clockout_location_id": null, - "created_at": null, - "updated_at": null, - "regular_seconds_worked": null, - "overtime_seconds_worked": null, - "doubletime_seconds_worked": null -} -``` - +## V1 Timecard + +Represents a timecard for an employee. + +### Structure + +`V1Timecard` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The timecard's unique ID. | +| `employee_id` | `String` | | The ID of the employee the timecard is associated with. | +| `deleted` | `Boolean` | Optional | If true, the timecard was deleted by the merchant, and it is no longer valid. | +| `clockin_time` | `String` | Optional | The clock-in time for the timecard, in ISO 8601 format. | +| `clockout_time` | `String` | Optional | The clock-out time for the timecard, in ISO 8601 format. Provide this value only if importing timecard information from another system. | +| `clockin_location_id` | `String` | Optional | The ID of the location the employee clocked in from. We strongly reccomend providing a clockin_location_id. Square uses the clockin_location_id to determine a timecard’s timezone and overtime rules. | +| `clockout_location_id` | `String` | Optional | The ID of the location the employee clocked out from. Provide this value only if importing timecard information from another system. | +| `created_at` | `String` | Optional | The time when the timecard was created, in ISO 8601 format. | +| `updated_at` | `String` | Optional | The time when the timecard was most recently updated, in ISO 8601 format. | +| `regular_seconds_worked` | `Float` | Optional | The total number of regular (non-overtime) seconds worked in the timecard. | +| `overtime_seconds_worked` | `Float` | Optional | The total number of overtime seconds worked in the timecard. | +| `doubletime_seconds_worked` | `Float` | Optional | The total number of doubletime seconds worked in the timecard. | + +### Example (as JSON) + +```json +{ + "id": null, + "employee_id": "employee_id0", + "deleted": null, + "clockin_time": null, + "clockout_time": null, + "clockin_location_id": null, + "clockout_location_id": null, + "created_at": null, + "updated_at": null, + "regular_seconds_worked": null, + "overtime_seconds_worked": null, + "doubletime_seconds_worked": null +} +``` + diff --git a/doc/models/v1-update-category-request.md b/doc/models/v1-update-category-request.md index 87bcd127..c990d2c0 100644 --- a/doc/models/v1-update-category-request.md +++ b/doc/models/v1-update-category-request.md @@ -1,24 +1,24 @@ -## V1 Update Category Request - -### Structure - -`V1UpdateCategoryRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Category Hash`](/doc/models/v1-category.md) | V1Category | - -### Example (as JSON) - -```json -{ - "body": { - "id": null, - "name": null, - "v2_id": null - } -} -``` - +## V1 Update Category Request + +### Structure + +`V1UpdateCategoryRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Category Hash`](/doc/models/v1-category.md) | V1Category | + +### Example (as JSON) + +```json +{ + "body": { + "id": null, + "name": null, + "v2_id": null + } +} +``` + diff --git a/doc/models/v1-update-discount-request.md b/doc/models/v1-update-discount-request.md index cadb61d4..3b9a6843 100644 --- a/doc/models/v1-update-discount-request.md +++ b/doc/models/v1-update-discount-request.md @@ -1,29 +1,29 @@ -## V1 Update Discount Request - -### Structure - -`V1UpdateDiscountRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Discount Hash`](/doc/models/v1-discount.md) | V1Discount | - -### Example (as JSON) - -```json -{ - "body": { - "id": null, - "name": null, - "rate": null, - "amount_money": null, - "discount_type": null, - "pin_required": null, - "color": null, - "v2_id": null - } -} -``` - +## V1 Update Discount Request + +### Structure + +`V1UpdateDiscountRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Discount Hash`](/doc/models/v1-discount.md) | V1Discount | + +### Example (as JSON) + +```json +{ + "body": { + "id": null, + "name": null, + "rate": null, + "amount_money": null, + "discount_type": null, + "pin_required": null, + "color": null, + "v2_id": null + } +} +``` + diff --git a/doc/models/v1-update-employee-request.md b/doc/models/v1-update-employee-request.md index 4b6768c7..771791ce 100644 --- a/doc/models/v1-update-employee-request.md +++ b/doc/models/v1-update-employee-request.md @@ -1,31 +1,31 @@ -## V1 Update Employee Request - -### Structure - -`V1UpdateEmployeeRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Employee Hash`](/doc/models/v1-employee.md) | Represents one of a business's employees. | - -### Example (as JSON) - -```json -{ - "body": { - "id": null, - "first_name": "first_name6", - "last_name": "last_name4", - "role_ids": null, - "authorized_location_ids": null, - "email": null, - "status": null, - "external_id": null, - "created_at": null, - "updated_at": null - } -} -``` - +## V1 Update Employee Request + +### Structure + +`V1UpdateEmployeeRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Employee Hash`](/doc/models/v1-employee.md) | Represents one of a business's employees. | + +### Example (as JSON) + +```json +{ + "body": { + "id": null, + "first_name": "first_name6", + "last_name": "last_name4", + "role_ids": null, + "authorized_location_ids": null, + "email": null, + "status": null, + "external_id": null, + "created_at": null, + "updated_at": null + } +} +``` + diff --git a/doc/models/v1-update-employee-role-request.md b/doc/models/v1-update-employee-role-request.md index 0cc4a8a4..9f56f220 100644 --- a/doc/models/v1-update-employee-role-request.md +++ b/doc/models/v1-update-employee-role-request.md @@ -1,31 +1,31 @@ -## V1 Update Employee Role Request - -### Structure - -`V1UpdateEmployeeRoleRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) | V1EmployeeRole | - -### Example (as JSON) - -```json -{ - "body": { - "id": null, - "name": "name6", - "permissions": [ - "REGISTER_APPLY_RESTRICTED_DISCOUNTS", - "REGISTER_CHANGE_SETTINGS", - "REGISTER_EDIT_ITEM" - ], - "is_owner": null, - "created_at": null, - "updated_at": null - } -} -``` - +## V1 Update Employee Role Request + +### Structure + +`V1UpdateEmployeeRoleRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) | V1EmployeeRole | + +### Example (as JSON) + +```json +{ + "body": { + "id": null, + "name": "name6", + "permissions": [ + "REGISTER_APPLY_RESTRICTED_DISCOUNTS", + "REGISTER_CHANGE_SETTINGS", + "REGISTER_EDIT_ITEM" + ], + "is_owner": null, + "created_at": null, + "updated_at": null + } +} +``` + diff --git a/doc/models/v1-update-fee-request.md b/doc/models/v1-update-fee-request.md index e0eeb86c..66409cd4 100644 --- a/doc/models/v1-update-fee-request.md +++ b/doc/models/v1-update-fee-request.md @@ -1,31 +1,31 @@ -## V1 Update Fee Request - -### Structure - -`V1UpdateFeeRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Fee Hash`](/doc/models/v1-fee.md) | V1Fee | - -### Example (as JSON) - -```json -{ - "body": { - "id": null, - "name": null, - "rate": null, - "calculation_phase": null, - "adjustment_type": null, - "applies_to_custom_amounts": null, - "enabled": null, - "inclusion_type": null, - "type": null, - "v2_id": null - } -} -``` - +## V1 Update Fee Request + +### Structure + +`V1UpdateFeeRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Fee Hash`](/doc/models/v1-fee.md) | V1Fee | + +### Example (as JSON) + +```json +{ + "body": { + "id": null, + "name": null, + "rate": null, + "calculation_phase": null, + "adjustment_type": null, + "applies_to_custom_amounts": null, + "enabled": null, + "inclusion_type": null, + "type": null, + "v2_id": null + } +} +``` + diff --git a/doc/models/v1-update-item-request.md b/doc/models/v1-update-item-request.md index d09b03ac..2a2b0589 100644 --- a/doc/models/v1-update-item-request.md +++ b/doc/models/v1-update-item-request.md @@ -1,38 +1,38 @@ -## V1 Update Item Request - -### Structure - -`V1UpdateItemRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Item Hash`](/doc/models/v1-item.md) | V1Item | - -### Example (as JSON) - -```json -{ - "body": { - "id": null, - "name": null, - "description": null, - "type": null, - "color": null, - "abbreviation": null, - "visibility": null, - "available_online": null, - "master_image": null, - "category": null, - "variations": null, - "modifier_lists": null, - "fees": null, - "taxable": null, - "category_id": null, - "available_for_pickup": null, - "v2_id": null - } -} -``` - +## V1 Update Item Request + +### Structure + +`V1UpdateItemRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Item Hash`](/doc/models/v1-item.md) | V1Item | + +### Example (as JSON) + +```json +{ + "body": { + "id": null, + "name": null, + "description": null, + "type": null, + "color": null, + "abbreviation": null, + "visibility": null, + "available_online": null, + "master_image": null, + "category": null, + "variations": null, + "modifier_lists": null, + "fees": null, + "taxable": null, + "category_id": null, + "available_for_pickup": null, + "v2_id": null + } +} +``` + diff --git a/doc/models/v1-update-modifier-list-request.md b/doc/models/v1-update-modifier-list-request.md index c9ae7448..d9c30928 100644 --- a/doc/models/v1-update-modifier-list-request.md +++ b/doc/models/v1-update-modifier-list-request.md @@ -1,24 +1,24 @@ -## V1 Update Modifier List Request - -V1UpdateModifierListRequest - -### Structure - -`V1UpdateModifierListRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `String` | Optional | The modifier list's name. | -| `selection_type` | [`String (V1 Modifier List Selection Type)`](/doc/models/v1-modifier-list-selection-type.md) | Optional | - | - -### Example (as JSON) - -```json -{ - "name": null, - "selection_type": null -} -``` - +## V1 Update Modifier List Request + +V1UpdateModifierListRequest + +### Structure + +`V1UpdateModifierListRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `String` | Optional | The modifier list's name. | +| `selection_type` | [`String (V1 Modifier List Selection Type)`](/doc/models/v1-modifier-list-selection-type.md) | Optional | - | + +### Example (as JSON) + +```json +{ + "name": null, + "selection_type": null +} +``` + diff --git a/doc/models/v1-update-modifier-option-request.md b/doc/models/v1-update-modifier-option-request.md index ab642002..4e183b29 100644 --- a/doc/models/v1-update-modifier-option-request.md +++ b/doc/models/v1-update-modifier-option-request.md @@ -1,28 +1,28 @@ -## V1 Update Modifier Option Request - -### Structure - -`V1UpdateModifierOptionRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) | V1ModifierOption | - -### Example (as JSON) - -```json -{ - "body": { - "id": null, - "name": null, - "price_money": null, - "on_by_default": null, - "ordinal": null, - "modifier_list_id": null, - "v2_id": null - } -} -``` - +## V1 Update Modifier Option Request + +### Structure + +`V1UpdateModifierOptionRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) | V1ModifierOption | + +### Example (as JSON) + +```json +{ + "body": { + "id": null, + "name": null, + "price_money": null, + "on_by_default": null, + "ordinal": null, + "modifier_list_id": null, + "v2_id": null + } +} +``` + diff --git a/doc/models/v1-update-order-request-action.md b/doc/models/v1-update-order-request-action.md index 6de72110..a1ab6e26 100644 --- a/doc/models/v1-update-order-request-action.md +++ b/doc/models/v1-update-order-request-action.md @@ -1,14 +1,14 @@ -## V1 Update Order Request Action - -### Enumeration - -`V1UpdateOrderRequestAction` - -### Fields - -| Name | Description | -| --- | --- | -| `COMPLETE` | - | -| `CANCEL` | - | -| `REFUND` | - | - +## V1 Update Order Request Action + +### Enumeration + +`V1UpdateOrderRequestAction` + +### Fields + +| Name | Description | +| --- | --- | +| `COMPLETE` | - | +| `CANCEL` | - | +| `REFUND` | - | + diff --git a/doc/models/v1-update-order-request.md b/doc/models/v1-update-order-request.md index 914e3042..fb0b0625 100644 --- a/doc/models/v1-update-order-request.md +++ b/doc/models/v1-update-order-request.md @@ -1,30 +1,30 @@ -## V1 Update Order Request - -V1UpdateOrderRequest - -### Structure - -`V1UpdateOrderRequest` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `action` | [`String (V1 Update Order Request Action)`](/doc/models/v1-update-order-request-action.md) | | - | -| `shipped_tracking_number` | `String` | Optional | The tracking number of the shipment associated with the order. Only valid if action is COMPLETE. | -| `completed_note` | `String` | Optional | A merchant-specified note about the completion of the order. Only valid if action is COMPLETE. | -| `refunded_note` | `String` | Optional | A merchant-specified note about the refunding of the order. Only valid if action is REFUND. | -| `canceled_note` | `String` | Optional | A merchant-specified note about the canceling of the order. Only valid if action is CANCEL. | - -### Example (as JSON) - -```json -{ - "action": "COMPLETE", - "shipped_tracking_number": null, - "completed_note": null, - "refunded_note": null, - "canceled_note": null -} -``` - +## V1 Update Order Request + +V1UpdateOrderRequest + +### Structure + +`V1UpdateOrderRequest` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `action` | [`String (V1 Update Order Request Action)`](/doc/models/v1-update-order-request-action.md) | | - | +| `shipped_tracking_number` | `String` | Optional | The tracking number of the shipment associated with the order. Only valid if action is COMPLETE. | +| `completed_note` | `String` | Optional | A merchant-specified note about the completion of the order. Only valid if action is COMPLETE. | +| `refunded_note` | `String` | Optional | A merchant-specified note about the refunding of the order. Only valid if action is REFUND. | +| `canceled_note` | `String` | Optional | A merchant-specified note about the canceling of the order. Only valid if action is CANCEL. | + +### Example (as JSON) + +```json +{ + "action": "COMPLETE", + "shipped_tracking_number": null, + "completed_note": null, + "refunded_note": null, + "canceled_note": null +} +``` + diff --git a/doc/models/v1-update-page-cell-request.md b/doc/models/v1-update-page-cell-request.md index 27a0275b..9e6fba18 100644 --- a/doc/models/v1-update-page-cell-request.md +++ b/doc/models/v1-update-page-cell-request.md @@ -1,27 +1,27 @@ -## V1 Update Page Cell Request - -### Structure - -`V1UpdatePageCellRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Page Cell Hash`](/doc/models/v1-page-cell.md) | V1PageCell | - -### Example (as JSON) - -```json -{ - "body": { - "page_id": null, - "row": null, - "column": null, - "object_type": null, - "object_id": null, - "placeholder_type": null - } -} -``` - +## V1 Update Page Cell Request + +### Structure + +`V1UpdatePageCellRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Page Cell Hash`](/doc/models/v1-page-cell.md) | V1PageCell | + +### Example (as JSON) + +```json +{ + "body": { + "page_id": null, + "row": null, + "column": null, + "object_type": null, + "object_id": null, + "placeholder_type": null + } +} +``` + diff --git a/doc/models/v1-update-page-request.md b/doc/models/v1-update-page-request.md index ac0e7e6a..2cbef7dc 100644 --- a/doc/models/v1-update-page-request.md +++ b/doc/models/v1-update-page-request.md @@ -1,25 +1,25 @@ -## V1 Update Page Request - -### Structure - -`V1UpdatePageRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Page Hash`](/doc/models/v1-page.md) | V1Page | - -### Example (as JSON) - -```json -{ - "body": { - "id": null, - "name": null, - "page_index": null, - "cells": null - } -} -``` - +## V1 Update Page Request + +### Structure + +`V1UpdatePageRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Page Hash`](/doc/models/v1-page.md) | V1Page | + +### Example (as JSON) + +```json +{ + "body": { + "id": null, + "name": null, + "page_index": null, + "cells": null + } +} +``` + diff --git a/doc/models/v1-update-timecard-request.md b/doc/models/v1-update-timecard-request.md index d7536863..986cd97a 100644 --- a/doc/models/v1-update-timecard-request.md +++ b/doc/models/v1-update-timecard-request.md @@ -1,33 +1,33 @@ -## V1 Update Timecard Request - -### Structure - -`V1UpdateTimecardRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Timecard Hash`](/doc/models/v1-timecard.md) | Represents a timecard for an employee. | - -### Example (as JSON) - -```json -{ - "body": { - "id": null, - "employee_id": "employee_id4", - "deleted": null, - "clockin_time": null, - "clockout_time": null, - "clockin_location_id": null, - "clockout_location_id": null, - "created_at": null, - "updated_at": null, - "regular_seconds_worked": null, - "overtime_seconds_worked": null, - "doubletime_seconds_worked": null - } -} -``` - +## V1 Update Timecard Request + +### Structure + +`V1UpdateTimecardRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Timecard Hash`](/doc/models/v1-timecard.md) | Represents a timecard for an employee. | + +### Example (as JSON) + +```json +{ + "body": { + "id": null, + "employee_id": "employee_id4", + "deleted": null, + "clockin_time": null, + "clockout_time": null, + "clockin_location_id": null, + "clockout_location_id": null, + "created_at": null, + "updated_at": null, + "regular_seconds_worked": null, + "overtime_seconds_worked": null, + "doubletime_seconds_worked": null + } +} +``` + diff --git a/doc/models/v1-update-variation-request.md b/doc/models/v1-update-variation-request.md index 0ddde8cc..09bd4262 100644 --- a/doc/models/v1-update-variation-request.md +++ b/doc/models/v1-update-variation-request.md @@ -1,33 +1,33 @@ -## V1 Update Variation Request - -### Structure - -`V1UpdateVariationRequest` - -### Fields - -| Name | Type | Description | -| --- | --- | --- | -| `body` | [`V1 Variation Hash`](/doc/models/v1-variation.md) | V1Variation | - -### Example (as JSON) - -```json -{ - "body": { - "id": null, - "name": null, - "item_id": null, - "ordinal": null, - "pricing_type": null, - "price_money": null, - "sku": null, - "track_inventory": null, - "inventory_alert_type": null, - "inventory_alert_threshold": null, - "user_data": null, - "v2_id": null - } -} -``` - +## V1 Update Variation Request + +### Structure + +`V1UpdateVariationRequest` + +### Fields + +| Name | Type | Description | +| --- | --- | --- | +| `body` | [`V1 Variation Hash`](/doc/models/v1-variation.md) | V1Variation | + +### Example (as JSON) + +```json +{ + "body": { + "id": null, + "name": null, + "item_id": null, + "ordinal": null, + "pricing_type": null, + "price_money": null, + "sku": null, + "track_inventory": null, + "inventory_alert_type": null, + "inventory_alert_threshold": null, + "user_data": null, + "v2_id": null + } +} +``` + diff --git a/doc/models/v1-variation-inventory-alert-type.md b/doc/models/v1-variation-inventory-alert-type.md index af141e37..c618d68f 100644 --- a/doc/models/v1-variation-inventory-alert-type.md +++ b/doc/models/v1-variation-inventory-alert-type.md @@ -1,17 +1,17 @@ -## V1 Variation Inventory Alert Type - -### Enumeration - -`V1VariationInventoryAlertType` - -### Fields - -| Name | Description | -| --- | --- | -| `LOW_QUANTITY` | - | -| `NONE` | - | -| `INVESTMENT` | - | -| `LOAN` | - | -| `SAVINGS` | - | -| `OTHER` | - | - +## V1 Variation Inventory Alert Type + +### Enumeration + +`V1VariationInventoryAlertType` + +### Fields + +| Name | Description | +| --- | --- | +| `LOW_QUANTITY` | - | +| `NONE` | - | +| `INVESTMENT` | - | +| `LOAN` | - | +| `SAVINGS` | - | +| `OTHER` | - | + diff --git a/doc/models/v1-variation-pricing-type.md b/doc/models/v1-variation-pricing-type.md index dbed5eab..61aceccb 100644 --- a/doc/models/v1-variation-pricing-type.md +++ b/doc/models/v1-variation-pricing-type.md @@ -1,13 +1,13 @@ -## V1 Variation Pricing Type - -### Enumeration - -`V1VariationPricingType` - -### Fields - -| Name | Description | -| --- | --- | -| `FIXED_PRICING` | - | -| `VARIABLE_PRICING` | - | - +## V1 Variation Pricing Type + +### Enumeration + +`V1VariationPricingType` + +### Fields + +| Name | Description | +| --- | --- | +| `FIXED_PRICING` | - | +| `VARIABLE_PRICING` | - | + diff --git a/doc/models/v1-variation.md b/doc/models/v1-variation.md index 4ed6ad21..7b4efb1d 100644 --- a/doc/models/v1-variation.md +++ b/doc/models/v1-variation.md @@ -1,44 +1,44 @@ -## V1 Variation - -V1Variation - -### Structure - -`V1Variation` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | The item variation's unique ID. | -| `name` | `String` | Optional | The item variation's name. | -| `item_id` | `String` | Optional | The ID of the variation's associated item. | -| `ordinal` | `Integer` | Optional | Indicates the variation's list position when displayed in Square Register and the merchant dashboard. If more than one variation for the same item has the same ordinal value, those variations are displayed in alphabetical order | -| `pricing_type` | [`String (V1 Variation Pricing Type)`](/doc/models/v1-variation-pricing-type.md) | Optional | - | -| `price_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | -| `sku` | `String` | Optional | The item variation's SKU, if any. | -| `track_inventory` | `Boolean` | Optional | If true, inventory tracking is active for the variation. | -| `inventory_alert_type` | [`String (V1 Variation Inventory Alert Type)`](/doc/models/v1-variation-inventory-alert-type.md) | Optional | - | -| `inventory_alert_threshold` | `Integer` | Optional | If the inventory quantity for the variation is less than or equal to this value and inventory_alert_type is LOW_QUANTITY, the variation displays an alert in the merchant dashboard. | -| `user_data` | `String` | Optional | Arbitrary metadata associated with the variation. Cannot exceed 255 characters. | -| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | - -### Example (as JSON) - -```json -{ - "id": null, - "name": null, - "item_id": null, - "ordinal": null, - "pricing_type": null, - "price_money": null, - "sku": null, - "track_inventory": null, - "inventory_alert_type": null, - "inventory_alert_threshold": null, - "user_data": null, - "v2_id": null -} -``` - +## V1 Variation + +V1Variation + +### Structure + +`V1Variation` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | The item variation's unique ID. | +| `name` | `String` | Optional | The item variation's name. | +| `item_id` | `String` | Optional | The ID of the variation's associated item. | +| `ordinal` | `Integer` | Optional | Indicates the variation's list position when displayed in Square Register and the merchant dashboard. If more than one variation for the same item has the same ordinal value, those variations are displayed in alphabetical order | +| `pricing_type` | [`String (V1 Variation Pricing Type)`](/doc/models/v1-variation-pricing-type.md) | Optional | - | +| `price_money` | [`V1 Money Hash`](/doc/models/v1-money.md) | Optional | - | +| `sku` | `String` | Optional | The item variation's SKU, if any. | +| `track_inventory` | `Boolean` | Optional | If true, inventory tracking is active for the variation. | +| `inventory_alert_type` | [`String (V1 Variation Inventory Alert Type)`](/doc/models/v1-variation-inventory-alert-type.md) | Optional | - | +| `inventory_alert_threshold` | `Integer` | Optional | If the inventory quantity for the variation is less than or equal to this value and inventory_alert_type is LOW_QUANTITY, the variation displays an alert in the merchant dashboard. | +| `user_data` | `String` | Optional | Arbitrary metadata associated with the variation. Cannot exceed 255 characters. | +| `v2_id` | `String` | Optional | The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID. | + +### Example (as JSON) + +```json +{ + "id": null, + "name": null, + "item_id": null, + "ordinal": null, + "pricing_type": null, + "price_money": null, + "sku": null, + "track_inventory": null, + "inventory_alert_type": null, + "inventory_alert_threshold": null, + "user_data": null, + "v2_id": null +} +``` + diff --git a/doc/models/void-transaction-response.md b/doc/models/void-transaction-response.md index 84c99196..a0781377 100644 --- a/doc/models/void-transaction-response.md +++ b/doc/models/void-transaction-response.md @@ -1,21 +1,21 @@ -## Void Transaction Response - -Defines the fields that are included in the response body of -a request to the [VoidTransaction](#endpoint-voidtransaction) endpoint. - -### Structure - -`VoidTransactionResponse` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | - -### Example (as JSON) - -```json -{} -``` - +## Void Transaction Response + +Defines the fields that are included in the response body of +a request to the [VoidTransaction](#endpoint-voidtransaction) endpoint. + +### Structure + +`VoidTransactionResponse` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`Array`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +### Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/webhook-events.md b/doc/models/webhook-events.md index 02857eaf..01a46390 100644 --- a/doc/models/webhook-events.md +++ b/doc/models/webhook-events.md @@ -1,14 +1,14 @@ -## Webhook Events - -The type of an event that triggers a webhook notification to an application. - -### Enumeration - -`WebhookEvents` - -### Fields - -| Name | Description | -| --- | --- | -| `Enum_inventorycountupdated` | The quantity was updated for a catalog item variation.
Webhook notification data is packaged as: [`InventoryCount[]`](#type-inventorychange). | - +## Webhook Events + +The type of an event that triggers a webhook notification to an application. + +### Enumeration + +`WebhookEvents` + +### Fields + +| Name | Description | +| --- | --- | +| `Enum_inventorycountupdated` | The quantity was updated for a catalog item variation.
Webhook notification data is packaged as: [`InventoryCount[]`](#type-inventorychange). | + diff --git a/doc/models/weekday.md b/doc/models/weekday.md index f2363766..5cd54d83 100644 --- a/doc/models/weekday.md +++ b/doc/models/weekday.md @@ -1,20 +1,20 @@ -## Weekday - -The days of the week. - -### Enumeration - -`Weekday` - -### Fields - -| Name | Description | -| --- | --- | -| `MON` | Monday | -| `TUE` | Tuesday | -| `WED` | Wednesday | -| `THU` | Thursday | -| `FRI` | Friday | -| `SAT` | Saturday | -| `SUN` | Sunday | - +## Weekday + +The days of the week. + +### Enumeration + +`Weekday` + +### Fields + +| Name | Description | +| --- | --- | +| `MON` | Monday | +| `TUE` | Tuesday | +| `WED` | Wednesday | +| `THU` | Thursday | +| `FRI` | Friday | +| `SAT` | Saturday | +| `SUN` | Sunday | + diff --git a/doc/models/workweek-config.md b/doc/models/workweek-config.md index be5ab45e..b0bcfe20 100644 --- a/doc/models/workweek-config.md +++ b/doc/models/workweek-config.md @@ -1,33 +1,33 @@ -## Workweek Config - -Sets the Day of the week and hour of the day that a business starts a -work week. Used for the calculation of overtime pay. - -### Structure - -`WorkweekConfig` - -### Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `String` | Optional | UUID for this object | -| `start_of_week` | [`String (Weekday)`](/doc/models/weekday.md) | | The days of the week. | -| `start_of_day_local_time` | `String` | | The local time at which a business week cuts over. Represented as a
string in `HH:MM` format (`HH:MM:SS` is also accepted, but seconds are
truncated). | -| `version` | `Integer` | Optional | Used for resolving concurrency issues; request will fail if version
provided does not match server version at time of request. If not provided,
Square executes a blind write; potentially overwriting data from another
write. | -| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC | -| `updated_at` | `String` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC | - -### Example (as JSON) - -```json -{ - "id": null, - "start_of_week": "MON", - "start_of_day_local_time": "start_of_day_local_time6", - "version": null, - "created_at": null, - "updated_at": null -} -``` - +## Workweek Config + +Sets the Day of the week and hour of the day that a business starts a +work week. Used for the calculation of overtime pay. + +### Structure + +`WorkweekConfig` + +### Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `String` | Optional | UUID for this object | +| `start_of_week` | [`String (Weekday)`](/doc/models/weekday.md) | | The days of the week. | +| `start_of_day_local_time` | `String` | | The local time at which a business week cuts over. Represented as a
string in `HH:MM` format (`HH:MM:SS` is also accepted, but seconds are
truncated). | +| `version` | `Integer` | Optional | Used for resolving concurrency issues; request will fail if version
provided does not match server version at time of request. If not provided,
Square executes a blind write; potentially overwriting data from another
write. | +| `created_at` | `String` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC | +| `updated_at` | `String` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC | + +### Example (as JSON) + +```json +{ + "id": null, + "start_of_week": "MON", + "start_of_day_local_time": "start_of_day_local_time6", + "version": null, + "created_at": null, + "updated_at": null +} +``` + diff --git a/doc/o-auth.md b/doc/o-auth.md index c6050eb2..b98d52c0 100644 --- a/doc/o-auth.md +++ b/doc/o-auth.md @@ -1,179 +1,179 @@ -# O Auth - -```ruby -o_auth_api = client.o_auth -``` - -## Class Name - -`OAuthApi` - -## Methods - -* [Renew Token](/doc/o-auth.md#renew-token) -* [Revoke Token](/doc/o-auth.md#revoke-token) -* [Obtain Token](/doc/o-auth.md#obtain-token) - -## Renew Token - -`RenewToken` is deprecated. For information about refreshing OAuth access tokens, see -[Renew OAuth Token](https://developer.squareup.com/docs/oauth-api/cookbook/renew-oauth-tokens). - - -Renews an OAuth access token before it expires. - -OAuth access tokens besides your application's personal access token expire after __30 days__. -You can also renew expired tokens within __15 days__ of their expiration. -You cannot renew an access token that has been expired for more than 15 days. -Instead, the associated user must re-complete the OAuth flow from the beginning. - -__Important:__ The `Authorization` header for this endpoint must have the -following format: - -``` -Authorization: Client APPLICATION_SECRET -``` - -Replace `APPLICATION_SECRET` with the application secret on the Credentials -page in the [application dashboard](https://connect.squareup.com/apps). - -:information_source: **Note** This endpoint does not require authentication. - -```ruby -def renew_token(client_id:, - body:, - authorization:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `client_id` | `String` | Template, Required | Your application's ID, available from the [application dashboard](https://connect.squareup.com/apps). | -| `body` | [`Renew Token Request Hash`](/doc/models/renew-token-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | -| `authorization` | `String` | Header, Required | Client APPLICATION_SECRET | - -### Response Type - -[`Renew Token Response Hash`](/doc/models/renew-token-response.md) - -### Example Usage - -```ruby -client_id = 'client_id8' -body = {} -body[:access_token] = 'ACCESS_TOKEN' -authorization = 'Authorization8' - -result = o_auth_api.renew_token(client_id: client_id, body: body, authorization: authorization) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Revoke Token - -Revokes an access token generated with the OAuth flow. - -If an account has more than one OAuth access token for your application, this -endpoint revokes all of them, regardless of which token you specify. When an -OAuth access token is revoked, all of the active subscriptions associated -with that OAuth token are canceled immediately. - -__Important:__ The `Authorization` header for this endpoint must have the -following format: - -``` -Authorization: Client APPLICATION_SECRET -``` - -Replace `APPLICATION_SECRET` with the application secret on the Credentials -page in the [application dashboard](https://connect.squareup.com/apps). - -:information_source: **Note** This endpoint does not require authentication. - -```ruby -def revoke_token(body:, - authorization:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Revoke Token Request Hash`](/doc/models/revoke-token-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | -| `authorization` | `String` | Header, Required | Client APPLICATION_SECRET | - -### Response Type - -[`Revoke Token Response Hash`](/doc/models/revoke-token-response.md) - -### Example Usage - -```ruby -body = {} -body[:client_id] = 'CLIENT_ID' -body[:access_token] = 'ACCESS_TOKEN' -authorization = 'Authorization8' - -result = o_auth_api.revoke_token(body: body, authorization: authorization) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Obtain Token - -Returns an OAuth access token. - -The endpoint supports distinct methods of obtaining OAuth access tokens. -Applications specify a method by adding the `grant_type` parameter -in the request and also provide relevant information. -For more information, see [OAuth access token management](/authz/oauth/how-it-works#oauth-access-token-management). - -__Note:__ Regardless of the method application specified, -the endpoint always returns two items; an OAuth access token and -a refresh token in the response. - -__OAuth tokens should only live on secure servers. Application clients -should never interact directly with OAuth tokens__. - -:information_source: **Note** This endpoint does not require authentication. - -```ruby -def obtain_token(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Obtain Token Request Hash`](/doc/models/obtain-token-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Obtain Token Response Hash`](/doc/models/obtain-token-response.md) - -### Example Usage - -```ruby -body = {} -body[:client_id] = 'client_id8' -body[:client_secret] = 'client_secret4' -body[:grant_type] = 'grant_type8' - -result = o_auth_api.obtain_token(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# O Auth + +```ruby +o_auth_api = client.o_auth +``` + +## Class Name + +`OAuthApi` + +## Methods + +* [Renew Token](/doc/o-auth.md#renew-token) +* [Revoke Token](/doc/o-auth.md#revoke-token) +* [Obtain Token](/doc/o-auth.md#obtain-token) + +## Renew Token + +`RenewToken` is deprecated. For information about refreshing OAuth access tokens, see +[Renew OAuth Token](https://developer.squareup.com/docs/oauth-api/cookbook/renew-oauth-tokens). + + +Renews an OAuth access token before it expires. + +OAuth access tokens besides your application's personal access token expire after __30 days__. +You can also renew expired tokens within __15 days__ of their expiration. +You cannot renew an access token that has been expired for more than 15 days. +Instead, the associated user must re-complete the OAuth flow from the beginning. + +__Important:__ The `Authorization` header for this endpoint must have the +following format: + +``` +Authorization: Client APPLICATION_SECRET +``` + +Replace `APPLICATION_SECRET` with the application secret on the Credentials +page in the [application dashboard](https://connect.squareup.com/apps). + +:information_source: **Note** This endpoint does not require authentication. + +```ruby +def renew_token(client_id:, + body:, + authorization:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `client_id` | `String` | Template, Required | Your application's ID, available from the [application dashboard](https://connect.squareup.com/apps). | +| `body` | [`Renew Token Request Hash`](/doc/models/renew-token-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | +| `authorization` | `String` | Header, Required | Client APPLICATION_SECRET | + +### Response Type + +[`Renew Token Response Hash`](/doc/models/renew-token-response.md) + +### Example Usage + +```ruby +client_id = 'client_id8' +body = {} +body[:access_token] = 'ACCESS_TOKEN' +authorization = 'Authorization8' + +result = o_auth_api.renew_token(client_id: client_id, body: body, authorization: authorization) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Revoke Token + +Revokes an access token generated with the OAuth flow. + +If an account has more than one OAuth access token for your application, this +endpoint revokes all of them, regardless of which token you specify. When an +OAuth access token is revoked, all of the active subscriptions associated +with that OAuth token are canceled immediately. + +__Important:__ The `Authorization` header for this endpoint must have the +following format: + +``` +Authorization: Client APPLICATION_SECRET +``` + +Replace `APPLICATION_SECRET` with the application secret on the Credentials +page in the [application dashboard](https://connect.squareup.com/apps). + +:information_source: **Note** This endpoint does not require authentication. + +```ruby +def revoke_token(body:, + authorization:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Revoke Token Request Hash`](/doc/models/revoke-token-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | +| `authorization` | `String` | Header, Required | Client APPLICATION_SECRET | + +### Response Type + +[`Revoke Token Response Hash`](/doc/models/revoke-token-response.md) + +### Example Usage + +```ruby +body = {} +body[:client_id] = 'CLIENT_ID' +body[:access_token] = 'ACCESS_TOKEN' +authorization = 'Authorization8' + +result = o_auth_api.revoke_token(body: body, authorization: authorization) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Obtain Token + +Returns an OAuth access token. + +The endpoint supports distinct methods of obtaining OAuth access tokens. +Applications specify a method by adding the `grant_type` parameter +in the request and also provide relevant information. +For more information, see [OAuth access token management](https://developer.squareup.com/docs/authz/oauth/how-it-works#oauth-access-token-management). + +__Note:__ Regardless of the method application specified, +the endpoint always returns two items; an OAuth access token and +a refresh token in the response. + +__OAuth tokens should only live on secure servers. Application clients +should never interact directly with OAuth tokens__. + +:information_source: **Note** This endpoint does not require authentication. + +```ruby +def obtain_token(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Obtain Token Request Hash`](/doc/models/obtain-token-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Obtain Token Response Hash`](/doc/models/obtain-token-response.md) + +### Example Usage + +```ruby +body = {} +body[:client_id] = 'client_id8' +body[:client_secret] = 'client_secret4' +body[:grant_type] = 'grant_type8' + +result = o_auth_api.obtain_token(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/orders.md b/doc/orders.md index 3bce80b0..b77be8bf 100644 --- a/doc/orders.md +++ b/doc/orders.md @@ -1,253 +1,268 @@ -# Orders - -```ruby -orders_api = client.orders -``` - -## Class Name - -`OrdersApi` - -## Methods - -* [Create Order](/doc/orders.md#create-order) -* [Batch Retrieve Orders](/doc/orders.md#batch-retrieve-orders) -* [Update Order](/doc/orders.md#update-order) -* [Search Orders](/doc/orders.md#search-orders) -* [Pay Order](/doc/orders.md#pay-order) - -## Create Order - -Creates an [Order](./models/order.md) which specifies products for -purchase, along with discounts, taxes, and other settings to apply to the purchase. - -To pay for a created order, please refer to the [Pay for Orders](/orders-api/pay-for-orders) -guide. - -You can modify an order after you create it by using the -[UpdateOrder](/doc/orders.md#updateorder) endpoint. Orders that have reached a terminal state -cannot be updated. - -To learn more about the Orders API, see the -[Orders API Overview](/products/orders/overview). - -```ruby -def create_order(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the business location to associate the order with. | -| `body` | [`Create Order Request Hash`](/doc/models/create-order-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Create Order Response Hash`](/doc/models/create-order-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} - -result = orders_api.create_order(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Batch Retrieve Orders - -Retrieves a set of [Order](./models/order.md)s by their IDs. - -If a given Order ID does not exist, the ID is ignored instead of generating an error. - -```ruby -def batch_retrieve_orders(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the orders' associated location. | -| `body` | [`Batch Retrieve Orders Request Hash`](/doc/models/batch-retrieve-orders-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Batch Retrieve Orders Response Hash`](/doc/models/batch-retrieve-orders-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} -body[:order_ids] = ['CAISEM82RcpmcFBM0TfOyiHV3es', 'CAISENgvlJ6jLWAzERDzjyHVybY'] - -result = orders_api.batch_retrieve_orders(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Order - -Updates an [Order](./models/orders.md) by referencing its `order_id` and `version`. - -To pay for an order, please refer to the [Pay for Orders](/orders-api/pay-for-orders) guide. - -To learn more about the Orders API, see the -[Orders API Overview](/products/orders/overview). - -```ruby -def update_order(body:, - location_id:, - order_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Update Order Request Hash`](/doc/models/update-order-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | -| `location_id` | `String` | Template, Required | - | -| `order_id` | `String` | Template, Required | - | - -### Response Type - -[`Update Order Response Hash`](/doc/models/update-order-response.md) - -### Example Usage - -```ruby -body = {} -location_id = 'location_id4' -order_id = 'order_id6' - -result = orders_api.update_order(body: body, location_id: location_id, order_id: order_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Search Orders - -Search all Orders for a merchant and return either [Orders](./models/order.md) or -[OrderEntries](./models/order-entries.md). - -Note that details for orders processed with Square Point of Sale while in offline mode may not be -transmitted to Square for up to 72 hours. Offline orders have a `created_at` value that reflects -the time the order was originally processed, not the time it was subsequently transmitted to -Square. Consequently, the SearchOrder endpoint might list an offline Order chronologically -between online Orders that were seen in a previous request. - -When fetching additional pages using a `cursor`, the `query` must be equal -to the `query` used to fetch the first page of results. - -```ruby -def search_orders(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Search Orders Request Hash`](/doc/models/search-orders-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Search Orders Response Hash`](/doc/models/search-orders-response.md) - -### Example Usage - -```ruby -body = {} -body[:location_ids] = ['057P5VYJ4A5X1', '18YC4JDH91E1H'] -body[:query] = {} -body[:query][:filter] = {} -body[:query][:filter][:state_filter] = {} -body[:query][:filter][:state_filter][:states] = ['COMPLETED'] -body[:query][:filter][:date_time_filter] = {} -body[:query][:filter][:date_time_filter][:closed_at] = {} -body[:query][:filter][:date_time_filter][:closed_at][:start_at] = '2018-03-03T20:00:00+00:00' -body[:query][:filter][:date_time_filter][:closed_at][:end_at] = '2019-03-04T21:54:45+00:00' -body[:query][:sort] = {} -body[:query][:sort][:sort_field] = 'CLOSED_AT' -body[:query][:sort][:sort_order] = 'DESC' -body[:limit] = 3 -body[:return_entries] = true - -result = orders_api.search_orders(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Pay Order - -Pay for an [order](./models/order.md) using one or more approved [payments](./models/payments.md), -or settle an order with a total of `0`. - -The total of the `payments_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](/doc/payments.md#createpayment). -Any approved payments that reference the same `order_id` not specified in the -`payment_ids` will be canceled. -- Be approved with [delayed capture](/payments-api/take-payments#delayed-capture). -Using a delayed capture payment with PayOrder will complete the approved payment. - -Learn how to [pay for orders with a single payment using the Payments API](/orders-api/pay-for-orders). - -```ruby -def pay_order(order_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `order_id` | `String` | Template, Required | The ID of the order being paid. | -| `body` | [`Pay Order Request Hash`](/doc/models/pay-order-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Pay Order Response Hash`](/doc/models/pay-order-response.md) - -### Example Usage - -```ruby -order_id = 'order_id6' -body = {} -body[:idempotency_key] = 'c043a359-7ad9-4136-82a9-c3f1d66dcbff' -body[:payment_ids] = ['EnZdNAlWCmfh6Mt5FMNST1o7taB', '0LRiVlbXVwe8ozu4KbZxd12mvaB'] - -result = orders_api.pay_order(order_id: order_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Orders + +```ruby +orders_api = client.orders +``` + +## Class Name + +`OrdersApi` + +## Methods + +* [Create Order](/doc/orders.md#create-order) +* [Batch Retrieve Orders](/doc/orders.md#batch-retrieve-orders) +* [Update Order](/doc/orders.md#update-order) +* [Search Orders](/doc/orders.md#search-orders) +* [Pay Order](/doc/orders.md#pay-order) + +## Create Order + +Creates a new [Order](#type-order) which can include information on products for +purchase and settings to apply to the purchase. + +To pay for a created order, please refer to the [Pay for Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders) +guide. + +You can modify open orders using the [UpdateOrder](#endpoint-orders-updateorder) endpoint. + +To learn more about the Orders API, see the +[Orders API Overview](https://developer.squareup.com/docs/orders-api/what-it-does). + +```ruby +def create_order(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the business location to associate the order with. | +| `body` | [`Create Order Request Hash`](/doc/models/create-order-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Create Order Response Hash`](/doc/models/create-order-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} + +result = orders_api.create_order(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Batch Retrieve Orders + +Retrieves a set of [Order](#type-order)s by their IDs. + +If a given Order ID does not exist, the ID is ignored instead of generating an error. + +```ruby +def batch_retrieve_orders(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the orders' associated location. | +| `body` | [`Batch Retrieve Orders Request Hash`](/doc/models/batch-retrieve-orders-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Batch Retrieve Orders Response Hash`](/doc/models/batch-retrieve-orders-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} +body[:order_ids] = ['CAISEM82RcpmcFBM0TfOyiHV3es', 'CAISENgvlJ6jLWAzERDzjyHVybY'] + +result = orders_api.batch_retrieve_orders(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Order + +Updates an open [Order](#type-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](https://developer.squareup.com/docs/orders-api/manage-orders#sparse-order-objects) +containing only the fields to update and the version the update is +being applied to. +- If deleting fields, the [dot notation paths](https://developer.squareup.com/docs/orders-api/manage-orders#on-dot-notation) +identifying fields to clear. + +To pay for an order, please refer to the [Pay for Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders) guide. + +To learn more about the Orders API, see the +[Orders API Overview](https://developer.squareup.com/docs/orders-api/what-it-does). + +```ruby +def update_order(location_id:, + order_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the order's associated location. | +| `order_id` | `String` | Template, Required | The ID of the order to update. | +| `body` | [`Update Order Request Hash`](/doc/models/update-order-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Update Order Response Hash`](/doc/models/update-order-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +order_id = 'order_id6' +body = {} + +result = orders_api.update_order(location_id: location_id, order_id: order_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Search Orders + +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 (e.g. Point of Sale, Invoices, Connect APIs, etc). + +SearchOrders requests need to specify which locations to search and define a +[`SearchOrdersQuery`](#type-searchordersquery) object which controls +how to sort or filter the results. Your SearchOrdersQuery can: + + Set filter criteria. + Set sort order. + Determine whether to return results as complete Order objects, or as +[OrderEntry](#type-orderentry) objects. + +Note that details for orders processed with Square Point of Sale while in +offline mode may 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. + +```ruby +def search_orders(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Search Orders Request Hash`](/doc/models/search-orders-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Search Orders Response Hash`](/doc/models/search-orders-response.md) + +### Example Usage + +```ruby +body = {} +body[:location_ids] = ['057P5VYJ4A5X1', '18YC4JDH91E1H'] +body[:query] = {} +body[:query][:filter] = {} +body[:query][:filter][:state_filter] = {} +body[:query][:filter][:state_filter][:states] = ['COMPLETED'] +body[:query][:filter][:date_time_filter] = {} +body[:query][:filter][:date_time_filter][:closed_at] = {} +body[:query][:filter][:date_time_filter][:closed_at][:start_at] = '2018-03-03T20:00:00+00:00' +body[:query][:filter][:date_time_filter][:closed_at][:end_at] = '2019-03-04T21:54:45+00:00' +body[:query][:sort] = {} +body[:query][:sort][:sort_field] = 'CLOSED_AT' +body[:query][:sort][:sort_order] = 'DESC' +body[:limit] = 3 +body[:return_entries] = true + +result = orders_api.search_orders(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Pay Order + +Pay for an [order](#type-order) using one or more approved [payments](#type-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](#endpoint-payments-createpayment). +Any approved payments that reference the same `order_id` not specified in the +`payment_ids` will be canceled. +- Be approved with [delayed capture](https://developer.squareup.com/docs/payments-api/take-payments#delayed-capture). +Using a delayed capture payment with PayOrder will complete the approved payment. + +Learn how to [pay for orders with a single payment using the Payments API](https://developer.squareup.com/docs/orders-api/pay-for-orders). + +```ruby +def pay_order(order_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `order_id` | `String` | Template, Required | The ID of the order being paid. | +| `body` | [`Pay Order Request Hash`](/doc/models/pay-order-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Pay Order Response Hash`](/doc/models/pay-order-response.md) + +### Example Usage + +```ruby +order_id = 'order_id6' +body = {} +body[:idempotency_key] = 'c043a359-7ad9-4136-82a9-c3f1d66dcbff' +body[:payment_ids] = ['EnZdNAlWCmfh6Mt5FMNST1o7taB', '0LRiVlbXVwe8ozu4KbZxd12mvaB'] + +result = orders_api.pay_order(order_id: order_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/payments.md b/doc/payments.md index d8dc269d..3aaad82a 100644 --- a/doc/payments.md +++ b/doc/payments.md @@ -1,267 +1,267 @@ -# Payments - -```ruby -payments_api = client.payments -``` - -## Class Name - -`PaymentsApi` - -## Methods - -* [List Payments](/doc/payments.md#list-payments) -* [Create Payment](/doc/payments.md#create-payment) -* [Cancel Payment by Idempotency Key](/doc/payments.md#cancel-payment-by-idempotency-key) -* [Get Payment](/doc/payments.md#get-payment) -* [Cancel Payment](/doc/payments.md#cancel-payment) -* [Complete Payment](/doc/payments.md#complete-payment) - -## List Payments - -Retrieves a list of payments taken by the account making the request. - -Max results per page: 100 - -```ruby -def list_payments(begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil, - location_id: nil, - total: nil, - last_4: nil, - card_brand: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `begin_time` | `String` | Query, Optional | Timestamp for the beginning of the reporting period, in RFC 3339 format.
Inclusive. Default: The current time minus one year. | -| `end_time` | `String` | Query, Optional | Timestamp for the end of the requested reporting period, in RFC 3339 format.

Default: The current time. | -| `sort_order` | `String` | Query, Optional | The order in which results are listed.
- `ASC` - oldest to newest
- `DESC` - newest to oldest (default). | -| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](/basics/api101/pagination) for more information. | -| `location_id` | `String` | Query, Optional | ID of location associated with payment | -| `total` | `Long` | Query, Optional | The exact amount in the total_money for a `Payment`. | -| `last_4` | `String` | Query, Optional | The last 4 digits of `Payment` card. | -| `card_brand` | `String` | Query, Optional | The brand of `Payment` card. For example, `VISA` | - -### Response Type - -[`List Payments Response Hash`](/doc/models/list-payments-response.md) - -### Example Usage - -```ruby -result = payments_api.list_payments() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Payment - -Charges a payment source, for example, a card -represented by customer's card on file or a card nonce. In addition -to the payment source, the request must also include the -amount to accept for the payment. - -There are several optional parameters that you can include in the request. -For example, tip money, whether to autocomplete the payment, or a reference ID -to correlate this payment with another system. -For more information about these -payment options, see [Take Payments](/payments-api/take-payments). - -The `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required -to enable application fees. - -```ruby -def create_payment(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Create Payment Request Hash`](/doc/models/create-payment-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Create Payment Response Hash`](/doc/models/create-payment-response.md) - -### Example Usage - -```ruby -body = {} -body[:source_id] = 'ccof:uIbfJXhXETSP197M3GB' -body[:idempotency_key] = '4935a656-a929-4792-b97c-8848be85c27c' -body[:amount_money] = {} -body[:amount_money][:amount] = 200 -body[:amount_money][:currency] = 'USD' -body[:app_fee_money] = {} -body[:app_fee_money][:amount] = 10 -body[:app_fee_money][:currency] = 'USD' -body[:autocomplete] = true -body[:customer_id] = 'VDKXEEKPJN48QDG3BGGFAK05P8' -body[:location_id] = 'XK3DBG77NJBFX' -body[:reference_id] = '123456' -body[:note] = 'Brief description' - -result = payments_api.create_payment(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Cancel Payment by Idempotency Key - -Cancels a payment identified by the idenpotency key that is specified the request. - -Use this method when status of a CreatePayment request is unknown. -For example, after you send a CreatePayment -request a network error occurs and you don't get a response. In this case, you can direct -Square to cancel the payment using this endpoint. In the request, you provide the same idempotency -key that you provided in your CreatePayment request you want to cancel. After cancelling the -payment, you can submit your CreatePayment request again. -Note that if no payment with the specified idempotency key is found, no action is taken, the end -point returns successfully. - -```ruby -def cancel_payment_by_idempotency_key(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Cancel Payment by Idempotency Key Request Hash`](/doc/models/cancel-payment-by-idempotency-key-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Cancel Payment by Idempotency Key Response Hash`](/doc/models/cancel-payment-by-idempotency-key-response.md) - -### Example Usage - -```ruby -body = {} -body[:idempotency_key] = 'a7e36d40-d24b-11e8-b568-0800200c9a66' - -result = payments_api.cancel_payment_by_idempotency_key(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Get Payment - -Retrieves details for a specific Payment. - -```ruby -def get_payment(payment_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `payment_id` | `String` | Template, Required | Unique ID for the desired `Payment`. | - -### Response Type - -[`Get Payment Response Hash`](/doc/models/get-payment-response.md) - -### Example Usage - -```ruby -payment_id = 'payment_id0' - -result = payments_api.get_payment(payment_id: payment_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Cancel Payment - -Cancels a payment. If you set `autocomplete` to false when creating a payment, -you can cancel the payment using this endpoint. For more information, see -[Delayed Payments](/payments-api/take-payments#delayed-payments). - -```ruby -def cancel_payment(payment_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `payment_id` | `String` | Template, Required | `payment_id` identifying the payment to be canceled. | - -### Response Type - -[`Cancel Payment Response Hash`](/doc/models/cancel-payment-response.md) - -### Example Usage - -```ruby -payment_id = 'payment_id0' - -result = payments_api.cancel_payment(payment_id: payment_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Complete Payment - -Completes a payment. - -By default, payments are set to complete immediately after they are created. -If you set autocomplete to false when creating a payment, -you can complete the payment using this endpoint. For more information, see -[Delayed Payments](/payments-api/take-payments#delayed-payments). - -```ruby -def complete_payment(payment_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `payment_id` | `String` | Template, Required | Unique ID identifying the payment to be completed. | - -### Response Type - -[`Complete Payment Response Hash`](/doc/models/complete-payment-response.md) - -### Example Usage - -```ruby -payment_id = 'payment_id0' - -result = payments_api.complete_payment(payment_id: payment_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Payments + +```ruby +payments_api = client.payments +``` + +## Class Name + +`PaymentsApi` + +## Methods + +* [List Payments](/doc/payments.md#list-payments) +* [Create Payment](/doc/payments.md#create-payment) +* [Cancel Payment by Idempotency Key](/doc/payments.md#cancel-payment-by-idempotency-key) +* [Get Payment](/doc/payments.md#get-payment) +* [Cancel Payment](/doc/payments.md#cancel-payment) +* [Complete Payment](/doc/payments.md#complete-payment) + +## List Payments + +Retrieves a list of payments taken by the account making the request. + +Max results per page: 100 + +```ruby +def list_payments(begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil, + location_id: nil, + total: nil, + last_4: nil, + card_brand: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `begin_time` | `String` | Query, Optional | Timestamp for the beginning of the reporting period, in RFC 3339 format.
Inclusive. Default: The current time minus one year. | +| `end_time` | `String` | Query, Optional | Timestamp for the end of the requested reporting period, in RFC 3339 format.

Default: The current time. | +| `sort_order` | `String` | Query, Optional | The order in which results are listed.
- `ASC` - oldest to newest
- `DESC` - newest to oldest (default). | +| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `location_id` | `String` | Query, Optional | ID of location associated with payment | +| `total` | `Long` | Query, Optional | The exact amount in the total_money for a `Payment`. | +| `last_4` | `String` | Query, Optional | The last 4 digits of `Payment` card. | +| `card_brand` | `String` | Query, Optional | The brand of `Payment` card. For example, `VISA` | + +### Response Type + +[`List Payments Response Hash`](/doc/models/list-payments-response.md) + +### Example Usage + +```ruby +result = payments_api.list_payments() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Payment + +Charges a payment source, for example, a card +represented by customer's card on file or a card nonce. In addition +to the payment source, the request must also include the +amount to accept for the payment. + +There are several optional parameters that you can include in the request. +For example, tip money, whether to autocomplete the payment, or a reference ID +to correlate this payment with another system. +For more information about these +payment options, see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments). + +The `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required +to enable application fees. + +```ruby +def create_payment(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Create Payment Request Hash`](/doc/models/create-payment-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Create Payment Response Hash`](/doc/models/create-payment-response.md) + +### Example Usage + +```ruby +body = {} +body[:source_id] = 'ccof:uIbfJXhXETSP197M3GB' +body[:idempotency_key] = '4935a656-a929-4792-b97c-8848be85c27c' +body[:amount_money] = {} +body[:amount_money][:amount] = 200 +body[:amount_money][:currency] = 'USD' +body[:app_fee_money] = {} +body[:app_fee_money][:amount] = 10 +body[:app_fee_money][:currency] = 'USD' +body[:autocomplete] = true +body[:customer_id] = 'VDKXEEKPJN48QDG3BGGFAK05P8' +body[:location_id] = 'XK3DBG77NJBFX' +body[:reference_id] = '123456' +body[:note] = 'Brief description' + +result = payments_api.create_payment(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Cancel Payment by Idempotency Key + +Cancels (voids) a payment identified by the idempotency key that is specified in the request. + +Use this method when status of a CreatePayment request is unknown. +For example, after you send a CreatePayment +request a network error occurs and you don't get a response. In this case, you can direct +Square to cancel the payment using this endpoint. In the request, you provide the same idempotency +key that you provided in your CreatePayment request you want to cancel. After cancelling the +payment, you can submit your CreatePayment request again. +Note that if no payment with the specified idempotency key is found, no action is taken, the end +point returns successfully. + +```ruby +def cancel_payment_by_idempotency_key(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Cancel Payment by Idempotency Key Request Hash`](/doc/models/cancel-payment-by-idempotency-key-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Cancel Payment by Idempotency Key Response Hash`](/doc/models/cancel-payment-by-idempotency-key-response.md) + +### Example Usage + +```ruby +body = {} +body[:idempotency_key] = 'a7e36d40-d24b-11e8-b568-0800200c9a66' + +result = payments_api.cancel_payment_by_idempotency_key(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Get Payment + +Retrieves details for a specific Payment. + +```ruby +def get_payment(payment_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `payment_id` | `String` | Template, Required | Unique ID for the desired `Payment`. | + +### Response Type + +[`Get Payment Response Hash`](/doc/models/get-payment-response.md) + +### Example Usage + +```ruby +payment_id = 'payment_id0' + +result = payments_api.get_payment(payment_id: payment_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Cancel Payment + +Cancels (voids) a payment. If you set `autocomplete` to false when creating a payment, +you can cancel the payment using this endpoint. For more information, see +[Delayed Payments](https://developer.squareup.com/docs/payments-api/take-payments#delayed-payments). + +```ruby +def cancel_payment(payment_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `payment_id` | `String` | Template, Required | `payment_id` identifying the payment to be canceled. | + +### Response Type + +[`Cancel Payment Response Hash`](/doc/models/cancel-payment-response.md) + +### Example Usage + +```ruby +payment_id = 'payment_id0' + +result = payments_api.cancel_payment(payment_id: payment_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Complete Payment + +Completes (captures) a payment. + +By default, payments are set to complete immediately after they are created. +If you set autocomplete to false when creating a payment, you can complete (capture) +the payment using this endpoint. For more information, see +[Delayed Payments](https://developer.squareup.com/docs/payments-api/take-payments#delayed-payments). + +```ruby +def complete_payment(payment_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `payment_id` | `String` | Template, Required | Unique ID identifying the payment to be completed. | + +### Response Type + +[`Complete Payment Response Hash`](/doc/models/complete-payment-response.md) + +### Example Usage + +```ruby +payment_id = 'payment_id0' + +result = payments_api.complete_payment(payment_id: payment_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/refunds.md b/doc/refunds.md index c39e425a..7be20ec1 100644 --- a/doc/refunds.md +++ b/doc/refunds.md @@ -1,131 +1,131 @@ -# Refunds - -```ruby -refunds_api = client.refunds -``` - -## Class Name - -`RefundsApi` - -## Methods - -* [List Payment Refunds](/doc/refunds.md#list-payment-refunds) -* [Refund Payment](/doc/refunds.md#refund-payment) -* [Get Payment Refund](/doc/refunds.md#get-payment-refund) - -## List Payment Refunds - -Retrieves a list of refunds for the account making the request. - -Max results per page: 100 - -```ruby -def list_payment_refunds(begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil, - location_id: nil, - status: nil, - source_type: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `begin_time` | `String` | Query, Optional | Timestamp for the beginning of the requested reporting period, in RFC 3339 format.

Default: The current time minus one year. | -| `end_time` | `String` | Query, Optional | Timestamp for the end of the requested reporting period, in RFC 3339 format.

Default: The current time. | -| `sort_order` | `String` | Query, Optional | The order in which results are listed.
- `ASC` - oldest to newest
- `DESC` - newest to oldest (default). | -| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](/basics/api101/pagination) for more information. | -| `location_id` | `String` | Query, Optional | ID of location associated with payment. | -| `status` | `String` | Query, Optional | If provided, only refunds with the given status are returned.
For a list of refund status values, see [PaymentRefund](./models/payment-refund.md).

Default: If omitted refunds are returned regardless of status. | -| `source_type` | `String` | Query, Optional | If provided, only refunds with the given source type are returned.
- `CARD` - List refunds only for payments where card was specified as payment
source.

Default: If omitted refunds are returned regardless of source type. | - -### Response Type - -[`List Payment Refunds Response Hash`](/doc/models/list-payment-refunds-response.md) - -### Example Usage - -```ruby -result = refunds_api.list_payment_refunds() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Refund Payment - -Refunds a payment. You can refund the entire payment amount or a -portion of it. For more information, see -[Payments and Refunds Overview](/payments-api/overview). - -```ruby -def refund_payment(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`Refund Payment Request Hash`](/doc/models/refund-payment-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Refund Payment Response Hash`](/doc/models/refund-payment-response.md) - -### Example Usage - -```ruby -body = {} -body[:idempotency_key] = 'a7e36d40-d24b-11e8-b568-0800200c9a66' -body[:amount_money] = {} -body[:amount_money][:amount] = 100 -body[:amount_money][:currency] = 'USD' -body[:payment_id] = 'UNOE3kv2BZwqHlJ830RCt5YCuaB' - -result = refunds_api.refund_payment(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Get Payment Refund - -Retrieves a specific `Refund` using the `refund_id`. - -```ruby -def get_payment_refund(refund_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `refund_id` | `String` | Template, Required | Unique ID for the desired `PaymentRefund`. | - -### Response Type - -[`Get Payment Refund Response Hash`](/doc/models/get-payment-refund-response.md) - -### Example Usage - -```ruby -refund_id = 'refund_id4' - -result = refunds_api.get_payment_refund(refund_id: refund_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Refunds + +```ruby +refunds_api = client.refunds +``` + +## Class Name + +`RefundsApi` + +## Methods + +* [List Payment Refunds](/doc/refunds.md#list-payment-refunds) +* [Refund Payment](/doc/refunds.md#refund-payment) +* [Get Payment Refund](/doc/refunds.md#get-payment-refund) + +## List Payment Refunds + +Retrieves a list of refunds for the account making the request. + +Max results per page: 100 + +```ruby +def list_payment_refunds(begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil, + location_id: nil, + status: nil, + source_type: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `begin_time` | `String` | Query, Optional | Timestamp for the beginning of the requested reporting period, in RFC 3339 format.

Default: The current time minus one year. | +| `end_time` | `String` | Query, Optional | Timestamp for the end of the requested reporting period, in RFC 3339 format.

Default: The current time. | +| `sort_order` | `String` | Query, Optional | The order in which results are listed.
- `ASC` - oldest to newest
- `DESC` - newest to oldest (default). | +| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | +| `location_id` | `String` | Query, Optional | ID of location associated with payment. | +| `status` | `String` | Query, Optional | If provided, only refunds with the given status are returned.
For a list of refund status values, see [PaymentRefund](#type-paymentrefund).

Default: If omitted refunds are returned regardless of status. | +| `source_type` | `String` | Query, Optional | If provided, only refunds with the given source type are returned.
- `CARD` - List refunds only for payments where card was specified as payment
source.

Default: If omitted refunds are returned regardless of source type. | + +### Response Type + +[`List Payment Refunds Response Hash`](/doc/models/list-payment-refunds-response.md) + +### Example Usage + +```ruby +result = refunds_api.list_payment_refunds() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Refund Payment + +Refunds a payment. You can refund the entire payment amount or a +portion of it. For more information, see +[Payments and Refunds Overview](https://developer.squareup.com/docs/payments-api/overview). + +```ruby +def refund_payment(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Refund Payment Request Hash`](/doc/models/refund-payment-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Refund Payment Response Hash`](/doc/models/refund-payment-response.md) + +### Example Usage + +```ruby +body = {} +body[:idempotency_key] = 'a7e36d40-d24b-11e8-b568-0800200c9a66' +body[:amount_money] = {} +body[:amount_money][:amount] = 100 +body[:amount_money][:currency] = 'USD' +body[:payment_id] = 'UNOE3kv2BZwqHlJ830RCt5YCuaB' + +result = refunds_api.refund_payment(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Get Payment Refund + +Retrieves a specific `Refund` using the `refund_id`. + +```ruby +def get_payment_refund(refund_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `refund_id` | `String` | Template, Required | Unique ID for the desired `PaymentRefund`. | + +### Response Type + +[`Get Payment Refund Response Hash`](/doc/models/get-payment-refund-response.md) + +### Example Usage + +```ruby +refund_id = 'refund_id4' + +result = refunds_api.get_payment_refund(refund_id: refund_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/reporting.md b/doc/reporting.md index 3d6e733d..13e72090 100644 --- a/doc/reporting.md +++ b/doc/reporting.md @@ -1,101 +1,101 @@ -# Reporting - -```ruby -reporting_api = client.reporting -``` - -## Class Name - -`ReportingApi` - -## Methods - -* [List Additional Recipient Receivable Refunds](/doc/reporting.md#list-additional-recipient-receivable-refunds) -* [List Additional Recipient Receivables](/doc/reporting.md#list-additional-recipient-receivables) - -## List Additional Recipient Receivable Refunds - -Returns a list of refunded transactions (across all possible originating locations) relating to monies -credited to the provided location ID by another Square account using the `additional_recipients` field in a transaction. - -Max results per [page](#paginatingresults): 50 - -```ruby -def list_additional_recipient_receivable_refunds(location_id:, - begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list AdditionalRecipientReceivableRefunds for. | -| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | -| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which results are listed in the response (`ASC` for
oldest first, `DESC` for newest first).

Default value: `DESC` | -| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](/basics/api101/pagination) for more information. | - -### Response Type - -[`List Additional Recipient Receivable Refunds Response Hash`](/doc/models/list-additional-recipient-receivable-refunds-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = reporting_api.list_additional_recipient_receivable_refunds(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Additional Recipient Receivables - -Returns a list of receivables (across all possible sending locations) representing monies credited -to the provided location ID by another Square account using the `additional_recipients` field in a transaction. - -Max results per [page](#paginatingresults): 50 - -```ruby -def list_additional_recipient_receivables(location_id:, - begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list AdditionalRecipientReceivables for. | -| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | -| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which results are listed in the response (`ASC` for
oldest first, `DESC` for newest first).

Default value: `DESC` | -| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](/basics/api101/pagination) for more information. | - -### Response Type - -[`List Additional Recipient Receivables Response Hash`](/doc/models/list-additional-recipient-receivables-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = reporting_api.list_additional_recipient_receivables(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Reporting + +```ruby +reporting_api = client.reporting +``` + +## Class Name + +`ReportingApi` + +## Methods + +* [List Additional Recipient Receivable Refunds](/doc/reporting.md#list-additional-recipient-receivable-refunds) +* [List Additional Recipient Receivables](/doc/reporting.md#list-additional-recipient-receivables) + +## List Additional Recipient Receivable Refunds + +Returns a list of refunded transactions (across all possible originating locations) relating to monies +credited to the provided location ID by another Square account using the `additional_recipients` field in a transaction. + +Max results per [page](#paginatingresults): 50 + +```ruby +def list_additional_recipient_receivable_refunds(location_id:, + begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list AdditionalRecipientReceivableRefunds for. | +| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | +| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which results are listed in the response (`ASC` for
oldest first, `DESC` for newest first).

Default value: `DESC` | +| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Response Type + +[`List Additional Recipient Receivable Refunds Response Hash`](/doc/models/list-additional-recipient-receivable-refunds-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = reporting_api.list_additional_recipient_receivable_refunds(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Additional Recipient Receivables + +Returns a list of receivables (across all possible sending locations) representing monies credited +to the provided location ID by another Square account using the `additional_recipients` field in a transaction. + +Max results per [page](#paginatingresults): 50 + +```ruby +def list_additional_recipient_receivables(location_id:, + begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list AdditionalRecipientReceivables for. | +| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | +| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which results are listed in the response (`ASC` for
oldest first, `DESC` for newest first).

Default value: `DESC` | +| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Response Type + +[`List Additional Recipient Receivables Response Hash`](/doc/models/list-additional-recipient-receivables-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = reporting_api.list_additional_recipient_receivables(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/transactions.md b/doc/transactions.md index cdb691f9..2862fae2 100644 --- a/doc/transactions.md +++ b/doc/transactions.md @@ -1,367 +1,367 @@ -# Transactions - -```ruby -transactions_api = client.transactions -``` - -## Class Name - -`TransactionsApi` - -## Methods - -* [List Refunds](/doc/transactions.md#list-refunds) -* [List Transactions](/doc/transactions.md#list-transactions) -* [Charge](/doc/transactions.md#charge) -* [Retrieve Transaction](/doc/transactions.md#retrieve-transaction) -* [Capture Transaction](/doc/transactions.md#capture-transaction) -* [Create Refund](/doc/transactions.md#create-refund) -* [Void Transaction](/doc/transactions.md#void-transaction) - -## List Refunds - -Lists refunds for one of a business's locations. - -Deprecated - recommend using [SearchOrders](/doc/orders.md#searchorders) - -In addition to full or partial tender refunds processed through Square APIs, -refunds may result from itemized returns or exchanges through Square's -Point of Sale applications. - -Refunds with a `status` of `PENDING` are not currently included in this -endpoint's response. - -Max results per [page](#paginatingresults): 50 - -```ruby -def list_refunds(location_id:, - begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list refunds for. | -| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | -| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which results are listed in the response (`ASC` for
oldest first, `DESC` for newest first).

Default value: `DESC` | -| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](/basics/api101/pagination) for more information. | - -### Response Type - -[`List Refunds Response Hash`](/doc/models/list-refunds-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = transactions_api.list_refunds(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Transactions - -Lists transactions for a particular location. - -Deprecated - recommend using [SearchOrders](/doc/orders.md#searchorders) - -Transactions include payment information from sales and exchanges and refund -information from returns and exchanges. - -Max results per [page](#paginatingresults): 50 - -```ruby -def list_transactions(location_id:, - begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list transactions for. | -| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | -| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | -| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which results are listed in the response (`ASC` for
oldest first, `DESC` for newest first).

Default value: `DESC` | -| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](/basics/api101/pagination) for more information. | - -### Response Type - -[`List Transactions Response Hash`](/doc/models/list-transactions-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = transactions_api.list_transactions(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Charge - -Charges a card represented by a card nonce or a customer's card on file. - -Deprecated - recommend using [CreatePayment](/doc/payments.md#createpayment) - -Your request to this endpoint must include _either_: - -- A value for the `card_nonce` parameter (to charge a card nonce generated -with the `SqPaymentForm`) -- Values for the `customer_card_id` and `customer_id` parameters (to charge -a customer's card on file) - -When this response is returned, the amount of Square's processing fee might not yet be -calculated. To obtain the processing fee, wait about ten seconds and call -[RetrieveTransaction](/doc/transactions.md#retrievetransaction). See the `processing_fee_money` -field of each [Tender included](#type-tender) in the transaction. - -```ruby -def charge(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to associate the created transaction with. | -| `body` | [`Charge Request Hash`](/doc/models/charge-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Charge Response Hash`](/doc/models/charge-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} -body[:idempotency_key] = '74ae1696-b1e3-4328-af6d-f1e04d947a13' -body[:amount_money] = {} -body[:amount_money][:amount] = 200 -body[:amount_money][:currency] = 'USD' -body[:card_nonce] = 'card_nonce_from_square_123' -body[:delay_capture] = false -body[:reference_id] = 'some optional reference id' -body[:note] = 'some optional note' -body[:billing_address] = {} -body[:billing_address][:address_line_1] = '500 Electric Ave' -body[:billing_address][:address_line_2] = 'Suite 600' -body[:billing_address][:locality] = 'New York' -body[:billing_address][:administrative_district_level_1] = 'NY' -body[:billing_address][:postal_code] = '10003' -body[:billing_address][:country] = 'US' -body[:shipping_address] = {} -body[:shipping_address][:address_line_1] = '123 Main St' -body[:shipping_address][:locality] = 'San Francisco' -body[:shipping_address][:administrative_district_level_1] = 'CA' -body[:shipping_address][:postal_code] = '94114' -body[:shipping_address][:country] = 'US' -body[:additional_recipients] = [] - - -body[:additional_recipients][0] = {} -body[:additional_recipients][0][:location_id] = '057P5VYJ4A5X1' -body[:additional_recipients][0][:description] = 'Application fees' -body[:additional_recipients][0][:amount_money] = {} -body[:additional_recipients][0][:amount_money][:amount] = 20 -body[:additional_recipients][0][:amount_money][:currency] = 'USD' - - -result = transactions_api.charge(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Transaction - -Retrieves details for a single transaction. - -Deprecated - recommend using [BatchRetrieveOrders](#endpoint-batchretrieveorders) - -```ruby -def retrieve_transaction(location_id:, - transaction_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the transaction's associated location. | -| `transaction_id` | `String` | Template, Required | The ID of the transaction to retrieve. | - -### Response Type - -[`Retrieve Transaction Response Hash`](/doc/models/retrieve-transaction-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -transaction_id = 'transaction_id8' - -result = transactions_api.retrieve_transaction(location_id: location_id, transaction_id: transaction_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Capture Transaction - -Captures a transaction that was created with the [Charge](/doc/transactions.md#charge) -endpoint with a `delay_capture` value of `true`. - -See the [Delay Capture of Funds](/transactions-api/cookbook/delay-capture) -recipe for more information. - -```ruby -def capture_transaction(location_id:, - transaction_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | - | -| `transaction_id` | `String` | Template, Required | - | - -### Response Type - -[`Capture Transaction Response Hash`](/doc/models/capture-transaction-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -transaction_id = 'transaction_id8' - -result = transactions_api.capture_transaction(location_id: location_id, transaction_id: transaction_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Refund - -Initiates a refund for a previously charged tender. - -Deprecated - recommend using [RefundPayment](/doc/refunds.md#refundpayment) - -You must issue a refund within 120 days of the associated payment. See -[this article](https://squareup.com/help/us/en/article/5060) for more information -on refund behavior. - -NOTE: Card-present transactions with Interac credit cards **cannot be -refunded using the Connect API**. Interac transactions must refunded -in-person (e.g., dipping the card using POS app). - -```ruby -def create_refund(location_id:, - transaction_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the original transaction's associated location. | -| `transaction_id` | `String` | Template, Required | The ID of the original transaction that includes the tender to refund. | -| `body` | [`Create Refund Request Hash`](/doc/models/create-refund-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`Create Refund Response Hash`](/doc/models/create-refund-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -transaction_id = 'transaction_id8' -body = {} -body[:idempotency_key] = '86ae1696-b1e3-4328-af6d-f1e04d947ad2' -body[:tender_id] = 'MtZRYYdDrYNQbOvV7nbuBvMF' -body[:reason] = 'a reason' -body[:amount_money] = {} -body[:amount_money][:amount] = 100 -body[:amount_money][:currency] = 'USD' - -result = transactions_api.create_refund(location_id: location_id, transaction_id: transaction_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Void Transaction - -Cancels a transaction that was created with the [Charge](/doc/transactions.md#charge) -endpoint with a `delay_capture` value of `true`. - -See the [Delay Capture of Funds](/transactions-api/cookbook/delay-capture) -recipe for more information. - -```ruby -def void_transaction(location_id:, - transaction_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | - | -| `transaction_id` | `String` | Template, Required | - | - -### Response Type - -[`Void Transaction Response Hash`](/doc/models/void-transaction-response.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -transaction_id = 'transaction_id8' - -result = transactions_api.void_transaction(location_id: location_id, transaction_id: transaction_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# Transactions + +```ruby +transactions_api = client.transactions +``` + +## Class Name + +`TransactionsApi` + +## Methods + +* [List Refunds](/doc/transactions.md#list-refunds) +* [List Transactions](/doc/transactions.md#list-transactions) +* [Charge](/doc/transactions.md#charge) +* [Retrieve Transaction](/doc/transactions.md#retrieve-transaction) +* [Capture Transaction](/doc/transactions.md#capture-transaction) +* [Create Refund](/doc/transactions.md#create-refund) +* [Void Transaction](/doc/transactions.md#void-transaction) + +## List Refunds + +Lists refunds for one of a business's locations. + +Deprecated - recommend using [SearchOrders](#endpoint-orders-searchorders) + +In addition to full or partial tender refunds processed through Square APIs, +refunds may result from itemized returns or exchanges through Square's +Point of Sale applications. + +Refunds with a `status` of `PENDING` are not currently included in this +endpoint's response. + +Max results per [page](#paginatingresults): 50 + +```ruby +def list_refunds(location_id:, + begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list refunds for. | +| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | +| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which results are listed in the response (`ASC` for
oldest first, `DESC` for newest first).

Default value: `DESC` | +| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Response Type + +[`List Refunds Response Hash`](/doc/models/list-refunds-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = transactions_api.list_refunds(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Transactions + +Lists transactions for a particular location. + +Deprecated - recommend using [SearchOrders](#endpoint-orders-searchorders) + +Transactions include payment information from sales and exchanges and refund +information from returns and exchanges. + +Max results per [page](#paginatingresults): 50 + +```ruby +def list_transactions(location_id:, + begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list transactions for. | +| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | +| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.

Default value: The current time. | +| `sort_order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which results are listed in the response (`ASC` for
oldest first, `DESC` for newest first).

Default value: `DESC` | +| `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | + +### Response Type + +[`List Transactions Response Hash`](/doc/models/list-transactions-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = transactions_api.list_transactions(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Charge + +Charges a card represented by a card nonce or a customer's card on file. + +Deprecated - recommend using [CreatePayment](#endpoint-payments-createpayment) + +Your request to this endpoint must include _either_: + +- A value for the `card_nonce` parameter (to charge a card nonce generated +with the `SqPaymentForm`) +- Values for the `customer_card_id` and `customer_id` parameters (to charge +a customer's card on file) + +When this response is returned, the amount of Square's processing fee might not yet be +calculated. To obtain the processing fee, wait about ten seconds and call +[RetrieveTransaction](#endpoint-transactions-retrievetransaction). See the `processing_fee_money` +field of each [Tender included](#type-tender) in the transaction. + +```ruby +def charge(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to associate the created transaction with. | +| `body` | [`Charge Request Hash`](/doc/models/charge-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Charge Response Hash`](/doc/models/charge-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} +body[:idempotency_key] = '74ae1696-b1e3-4328-af6d-f1e04d947a13' +body[:amount_money] = {} +body[:amount_money][:amount] = 200 +body[:amount_money][:currency] = 'USD' +body[:card_nonce] = 'card_nonce_from_square_123' +body[:delay_capture] = false +body[:reference_id] = 'some optional reference id' +body[:note] = 'some optional note' +body[:billing_address] = {} +body[:billing_address][:address_line_1] = '500 Electric Ave' +body[:billing_address][:address_line_2] = 'Suite 600' +body[:billing_address][:locality] = 'New York' +body[:billing_address][:administrative_district_level_1] = 'NY' +body[:billing_address][:postal_code] = '10003' +body[:billing_address][:country] = 'US' +body[:shipping_address] = {} +body[:shipping_address][:address_line_1] = '123 Main St' +body[:shipping_address][:locality] = 'San Francisco' +body[:shipping_address][:administrative_district_level_1] = 'CA' +body[:shipping_address][:postal_code] = '94114' +body[:shipping_address][:country] = 'US' +body[:additional_recipients] = [] + + +body[:additional_recipients][0] = {} +body[:additional_recipients][0][:location_id] = '057P5VYJ4A5X1' +body[:additional_recipients][0][:description] = 'Application fees' +body[:additional_recipients][0][:amount_money] = {} +body[:additional_recipients][0][:amount_money][:amount] = 20 +body[:additional_recipients][0][:amount_money][:currency] = 'USD' + + +result = transactions_api.charge(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Transaction + +Retrieves details for a single transaction. + +Deprecated - recommend using [BatchRetrieveOrders](#endpoint-batchretrieveorders) + +```ruby +def retrieve_transaction(location_id:, + transaction_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the transaction's associated location. | +| `transaction_id` | `String` | Template, Required | The ID of the transaction to retrieve. | + +### Response Type + +[`Retrieve Transaction Response Hash`](/doc/models/retrieve-transaction-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +transaction_id = 'transaction_id8' + +result = transactions_api.retrieve_transaction(location_id: location_id, transaction_id: transaction_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Capture Transaction + +Captures a transaction that was created with the [Charge](#endpoint-transactions-charge) +endpoint with a `delay_capture` value of `true`. + +See the [Delay Capture of Funds](https://developer.squareup.com/docs/transactions-api/cookbook/delay-capture) +recipe for more information. + +```ruby +def capture_transaction(location_id:, + transaction_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | - | +| `transaction_id` | `String` | Template, Required | - | + +### Response Type + +[`Capture Transaction Response Hash`](/doc/models/capture-transaction-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +transaction_id = 'transaction_id8' + +result = transactions_api.capture_transaction(location_id: location_id, transaction_id: transaction_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Refund + +Initiates a refund for a previously charged tender. + +Deprecated - recommend using [RefundPayment](#endpoint-refunds-refundpayment) + +You must issue a refund within 120 days of the associated payment. See +[this article](https://squareup.com/help/us/en/article/5060) for more information +on refund behavior. + +NOTE: Card-present transactions with Interac credit cards **cannot be +refunded using the Connect API**. Interac transactions must refunded +in-person (e.g., dipping the card using POS app). + +```ruby +def create_refund(location_id:, + transaction_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the original transaction's associated location. | +| `transaction_id` | `String` | Template, Required | The ID of the original transaction that includes the tender to refund. | +| `body` | [`Create Refund Request Hash`](/doc/models/create-refund-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`Create Refund Response Hash`](/doc/models/create-refund-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +transaction_id = 'transaction_id8' +body = {} +body[:idempotency_key] = '86ae1696-b1e3-4328-af6d-f1e04d947ad2' +body[:tender_id] = 'MtZRYYdDrYNQbOvV7nbuBvMF' +body[:reason] = 'a reason' +body[:amount_money] = {} +body[:amount_money][:amount] = 100 +body[:amount_money][:currency] = 'USD' + +result = transactions_api.create_refund(location_id: location_id, transaction_id: transaction_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Void Transaction + +Cancels a transaction that was created with the [Charge](#endpoint-transactions-charge) +endpoint with a `delay_capture` value of `true`. + +See the [Delay Capture of Funds](https://developer.squareup.com/docs/transactions-api/cookbook/delay-capture) +recipe for more information. + +```ruby +def void_transaction(location_id:, + transaction_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | - | +| `transaction_id` | `String` | Template, Required | - | + +### Response Type + +[`Void Transaction Response Hash`](/doc/models/void-transaction-response.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +transaction_id = 'transaction_id8' + +result = transactions_api.void_transaction(location_id: location_id, transaction_id: transaction_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/v1-employees.md b/doc/v1-employees.md index 32a43df8..a73b760b 100644 --- a/doc/v1-employees.md +++ b/doc/v1-employees.md @@ -1,662 +1,662 @@ -# V1 Employees - -```ruby -v1_employees_api = client.v1_employees -``` - -## Class Name - -`V1EmployeesApi` - -## Methods - -* [List Employees](/doc/v1-employees.md#list-employees) -* [Create Employee](/doc/v1-employees.md#create-employee) -* [Retrieve Employee](/doc/v1-employees.md#retrieve-employee) -* [Update Employee](/doc/v1-employees.md#update-employee) -* [List Employee Roles](/doc/v1-employees.md#list-employee-roles) -* [Create Employee Role](/doc/v1-employees.md#create-employee-role) -* [Retrieve Employee Role](/doc/v1-employees.md#retrieve-employee-role) -* [Update Employee Role](/doc/v1-employees.md#update-employee-role) -* [List Timecards](/doc/v1-employees.md#list-timecards) -* [Create Timecard](/doc/v1-employees.md#create-timecard) -* [Delete Timecard](/doc/v1-employees.md#delete-timecard) -* [Retrieve Timecard](/doc/v1-employees.md#retrieve-timecard) -* [Update Timecard](/doc/v1-employees.md#update-timecard) -* [List Timecard Events](/doc/v1-employees.md#list-timecard-events) -* [List Cash Drawer Shifts](/doc/v1-employees.md#list-cash-drawer-shifts) -* [Retrieve Cash Drawer Shift](/doc/v1-employees.md#retrieve-cash-drawer-shift) - -## List Employees - -Provides summary information for all of a business's employees. - -```ruby -def list_employees(order: nil, - begin_updated_at: nil, - end_updated_at: nil, - begin_created_at: nil, - end_created_at: nil, - status: nil, - external_id: nil, - limit: nil, - batch_token: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which employees are listed in the response, based on their created_at field. Default value: ASC | -| `begin_updated_at` | `String` | Query, Optional | If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format | -| `end_updated_at` | `String` | Query, Optional | If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format. | -| `begin_created_at` | `String` | Query, Optional | If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format. | -| `end_created_at` | `String` | Query, Optional | If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format. | -| `status` | [`String (V1 Employee Status)`](/doc/models/v1-employee-status.md) | Query, Optional | If provided, the endpoint returns only employee entities with the specified status (ACTIVE or INACTIVE). | -| `external_id` | `String` | Query, Optional | If provided, the endpoint returns only employee entities with the specified external_id. | -| `limit` | `Integer` | Query, Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | -| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Response Type - -[`Array`](/doc/models/v1-employee.md) - -### Example Usage - -```ruby -result = v1_employees_api.list_employees() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Employee - -Use the CreateEmployee endpoint to add an employee to a Square -account. Employees created with the Connect API have an initial status -of `INACTIVE`. Inactive employees cannot sign in to Square Point of Sale -until they are activated from the Square Dashboard. Employee status -cannot be changed with the Connect API. - - - -```ruby -def create_employee(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Employee Hash`](/doc/models/v1-employee.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Employee Hash`](/doc/models/v1-employee.md) - -### Example Usage - -```ruby -body = {} -body[:first_name] = 'first_name6' -body[:last_name] = 'last_name4' - -result = v1_employees_api.create_employee(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Employee - -Provides the details for a single employee. - -```ruby -def retrieve_employee(employee_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `employee_id` | `String` | Template, Required | The employee's ID. | - -### Response Type - -[`V1 Employee Hash`](/doc/models/v1-employee.md) - -### Example Usage - -```ruby -employee_id = 'employee_id0' - -result = v1_employees_api.retrieve_employee(employee_id: employee_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Employee - -UpdateEmployee - -```ruby -def update_employee(employee_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `employee_id` | `String` | Template, Required | The ID of the role to modify. | -| `body` | [`V1 Employee Hash`](/doc/models/v1-employee.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Employee Hash`](/doc/models/v1-employee.md) - -### Example Usage - -```ruby -employee_id = 'employee_id0' -body = {} -body[:first_name] = 'first_name6' -body[:last_name] = 'last_name4' - -result = v1_employees_api.update_employee(employee_id: employee_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Employee Roles - -Provides summary information for all of a business's employee roles. - -```ruby -def list_employee_roles(order: nil, - limit: nil, - batch_token: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which employees are listed in the response, based on their created_at field.Default value: ASC | -| `limit` | `Integer` | Query, Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | -| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Response Type - -[`Array`](/doc/models/v1-employee-role.md) - -### Example Usage - -```ruby -result = v1_employees_api.list_employee_roles() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Employee Role - -Creates an employee role you can then assign to employees. - -Square accounts can include any number of roles that can be assigned to -employees. These roles define the actions and permissions granted to an -employee with that role. For example, an employee with a "Shift Manager" -role might be able to issue refunds in Square Point of Sale, whereas an -employee with a "Clerk" role might not. - -Roles are assigned with the [V1UpdateEmployee](#endpoint-v1updateemployee) -endpoint. An employee can have only one role at a time. - -If an employee has no role, they have none of the permissions associated -with roles. All employees can accept payments with Square Point of Sale. - -```ruby -def create_employee_role(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) | Body, Required | An EmployeeRole object with a name and permissions, and an optional owner flag. | - -### Response Type - -[`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) - -### Example Usage - -```ruby -body = {} -body[:name] = 'name6' -body[:permissions] = ['REGISTER_APPLY_RESTRICTED_DISCOUNTS', 'REGISTER_CHANGE_SETTINGS', 'REGISTER_EDIT_ITEM'] - -result = v1_employees_api.create_employee_role(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Employee Role - -Provides the details for a single employee role. - -```ruby -def retrieve_employee_role(role_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `role_id` | `String` | Template, Required | The role's ID. | - -### Response Type - -[`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) - -### Example Usage - -```ruby -role_id = 'role_id6' - -result = v1_employees_api.retrieve_employee_role(role_id: role_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Employee Role - -Modifies the details of an employee role. - -```ruby -def update_employee_role(role_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `role_id` | `String` | Template, Required | The ID of the role to modify. | -| `body` | [`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) - -### Example Usage - -```ruby -role_id = 'role_id6' -body = {} -body[:name] = 'name6' -body[:permissions] = ['REGISTER_APPLY_RESTRICTED_DISCOUNTS', 'REGISTER_CHANGE_SETTINGS', 'REGISTER_EDIT_ITEM'] - -result = v1_employees_api.update_employee_role(role_id: role_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Timecards - -Provides summary information for all of a business's employee timecards. - -```ruby -def list_timecards(order: nil, - employee_id: nil, - begin_clockin_time: nil, - end_clockin_time: nil, - begin_clockout_time: nil, - end_clockout_time: nil, - begin_updated_at: nil, - end_updated_at: nil, - deleted: nil, - limit: nil, - batch_token: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which timecards are listed in the response, based on their created_at field. | -| `employee_id` | `String` | Query, Optional | If provided, the endpoint returns only timecards for the employee with the specified ID. | -| `begin_clockin_time` | `String` | Query, Optional | If filtering results by their clockin_time field, the beginning of the requested reporting period, in ISO 8601 format. | -| `end_clockin_time` | `String` | Query, Optional | If filtering results by their clockin_time field, the end of the requested reporting period, in ISO 8601 format. | -| `begin_clockout_time` | `String` | Query, Optional | If filtering results by their clockout_time field, the beginning of the requested reporting period, in ISO 8601 format. | -| `end_clockout_time` | `String` | Query, Optional | If filtering results by their clockout_time field, the end of the requested reporting period, in ISO 8601 format. | -| `begin_updated_at` | `String` | Query, Optional | If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format. | -| `end_updated_at` | `String` | Query, Optional | If filtering results by their updated_at field, the end of the requested reporting period, in ISO 8601 format. | -| `deleted` | `Boolean` | Query, Optional | If true, only deleted timecards are returned. If false, only valid timecards are returned.If you don't provide this parameter, both valid and deleted timecards are returned. | -| `limit` | `Integer` | Query, Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | -| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Response Type - -[`Array`](/doc/models/v1-timecard.md) - -### Example Usage - -```ruby -result = v1_employees_api.list_timecards() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Timecard - -Creates a timecard for an employee and clocks them in with an -`API_CREATE` event and a `clockin_time` set to the current time unless -the request provides a different value. To import timecards from another -system (rather than clocking someone in). Specify the `clockin_time` -and* `clockout_time` in the request. - -Timecards correspond to exactly one shift for a given employee, bounded -by the `clockin_time` and `clockout_time` fields. An employee is -considered clocked in if they have a timecard that doesn't have a -`clockout_time` set. An employee that is currently clocked in cannot -be clocked in a second time. - -```ruby -def create_timecard(body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `body` | [`V1 Timecard Hash`](/doc/models/v1-timecard.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Timecard Hash`](/doc/models/v1-timecard.md) - -### Example Usage - -```ruby -body = {} -body[:employee_id] = 'employee_id4' - -result = v1_employees_api.create_timecard(body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Timecard - -Deletes a timecard. Timecards can also be deleted through the -Square Dashboard. Deleted timecards are still accessible through -Connect API endpoints, but cannot be modified. The `deleted` field of -the `Timecard` object indicates whether the timecard has been deleted. - -*Note**: By default, deleted timecards appear alongside valid timecards in -results returned by the [ListTimecards](#endpoint-v1employees-listtimecards) -endpoint. To filter deleted timecards, include the `deleted` query -parameter in the list request. - - - -```ruby -def delete_timecard(timecard_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `timecard_id` | `String` | Template, Required | The ID of the timecard to delete. | - -### Response Type - -`Object` - -### Example Usage - -```ruby -timecard_id = 'timecard_id0' - -result = v1_employees_api.delete_timecard(timecard_id: timecard_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Timecard - -Provides the details for a single timecard. - - -```ruby -def retrieve_timecard(timecard_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `timecard_id` | `String` | Template, Required | The timecard's ID. | - -### Response Type - -[`V1 Timecard Hash`](/doc/models/v1-timecard.md) - -### Example Usage - -```ruby -timecard_id = 'timecard_id0' - -result = v1_employees_api.retrieve_timecard(timecard_id: timecard_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Timecard - -Modifies the details of a timecard with an `API_EDIT` event for -the timecard. Updating an active timecard with a `clockout_time` -clocks the employee out. - -```ruby -def update_timecard(timecard_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `timecard_id` | `String` | Template, Required | TThe ID of the timecard to modify. | -| `body` | [`V1 Timecard Hash`](/doc/models/v1-timecard.md) | Body, Required | An object containing the fields to POST for the request.
See the corresponding object definition for field details. | - -### Response Type - -[`V1 Timecard Hash`](/doc/models/v1-timecard.md) - -### Example Usage - -```ruby -timecard_id = 'timecard_id0' -body = {} -body[:employee_id] = 'employee_id4' - -result = v1_employees_api.update_timecard(timecard_id: timecard_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Timecard Events - -Provides summary information for all events associated with a -particular timecard. - - - -```ruby -def list_timecard_events(timecard_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `timecard_id` | `String` | Template, Required | The ID of the timecard to list events for. | - -### Response Type - -[`Array`](/doc/models/v1-timecard-event.md) - -### Example Usage - -```ruby -timecard_id = 'timecard_id0' - -result = v1_employees_api.list_timecard_events(timecard_id: timecard_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Cash Drawer Shifts - -Provides the details for all of a location's cash drawer shifts during a date range. The date range you specify cannot exceed 90 days. - -```ruby -def list_cash_drawer_shifts(location_id:, - order: nil, - begin_time: nil, - end_time: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list cash drawer shifts for. | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which cash drawer shifts are listed in the response, based on their created_at field. Default value: ASC | -| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time minus 90 days. | -| `end_time` | `String` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time. | - -### Response Type - -[`Array`](/doc/models/v1-cash-drawer-shift.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_employees_api.list_cash_drawer_shifts(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Cash Drawer Shift - -Provides the details for a single cash drawer shift, including all events that occurred during the shift. - -```ruby -def retrieve_cash_drawer_shift(location_id:, - shift_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list cash drawer shifts for. | -| `shift_id` | `String` | Template, Required | The shift's ID. | - -### Response Type - -[`V1 Cash Drawer Shift Hash`](/doc/models/v1-cash-drawer-shift.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -shift_id = 'shift_id0' - -result = v1_employees_api.retrieve_cash_drawer_shift(location_id: location_id, shift_id: shift_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# V1 Employees + +```ruby +v1_employees_api = client.v1_employees +``` + +## Class Name + +`V1EmployeesApi` + +## Methods + +* [List Employees](/doc/v1-employees.md#list-employees) +* [Create Employee](/doc/v1-employees.md#create-employee) +* [Retrieve Employee](/doc/v1-employees.md#retrieve-employee) +* [Update Employee](/doc/v1-employees.md#update-employee) +* [List Employee Roles](/doc/v1-employees.md#list-employee-roles) +* [Create Employee Role](/doc/v1-employees.md#create-employee-role) +* [Retrieve Employee Role](/doc/v1-employees.md#retrieve-employee-role) +* [Update Employee Role](/doc/v1-employees.md#update-employee-role) +* [List Timecards](/doc/v1-employees.md#list-timecards) +* [Create Timecard](/doc/v1-employees.md#create-timecard) +* [Delete Timecard](/doc/v1-employees.md#delete-timecard) +* [Retrieve Timecard](/doc/v1-employees.md#retrieve-timecard) +* [Update Timecard](/doc/v1-employees.md#update-timecard) +* [List Timecard Events](/doc/v1-employees.md#list-timecard-events) +* [List Cash Drawer Shifts](/doc/v1-employees.md#list-cash-drawer-shifts) +* [Retrieve Cash Drawer Shift](/doc/v1-employees.md#retrieve-cash-drawer-shift) + +## List Employees + +Provides summary information for all of a business's employees. + +```ruby +def list_employees(order: nil, + begin_updated_at: nil, + end_updated_at: nil, + begin_created_at: nil, + end_created_at: nil, + status: nil, + external_id: nil, + limit: nil, + batch_token: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which employees are listed in the response, based on their created_at field. Default value: ASC | +| `begin_updated_at` | `String` | Query, Optional | If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format | +| `end_updated_at` | `String` | Query, Optional | If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format. | +| `begin_created_at` | `String` | Query, Optional | If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format. | +| `end_created_at` | `String` | Query, Optional | If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format. | +| `status` | [`String (V1 Employee Status)`](/doc/models/v1-employee-status.md) | Query, Optional | If provided, the endpoint returns only employee entities with the specified status (ACTIVE or INACTIVE). | +| `external_id` | `String` | Query, Optional | If provided, the endpoint returns only employee entities with the specified external_id. | +| `limit` | `Integer` | Query, Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | +| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Response Type + +[`Array`](/doc/models/v1-employee.md) + +### Example Usage + +```ruby +result = v1_employees_api.list_employees() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Employee + +Use the CreateEmployee endpoint to add an employee to a Square +account. Employees created with the Connect API have an initial status +of `INACTIVE`. Inactive employees cannot sign in to Square Point of Sale +until they are activated from the Square Dashboard. Employee status +cannot be changed with the Connect API. + + + +```ruby +def create_employee(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Employee Hash`](/doc/models/v1-employee.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Employee Hash`](/doc/models/v1-employee.md) + +### Example Usage + +```ruby +body = {} +body[:first_name] = 'first_name6' +body[:last_name] = 'last_name4' + +result = v1_employees_api.create_employee(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Employee + +Provides the details for a single employee. + +```ruby +def retrieve_employee(employee_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `employee_id` | `String` | Template, Required | The employee's ID. | + +### Response Type + +[`V1 Employee Hash`](/doc/models/v1-employee.md) + +### Example Usage + +```ruby +employee_id = 'employee_id0' + +result = v1_employees_api.retrieve_employee(employee_id: employee_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Employee + +UpdateEmployee + +```ruby +def update_employee(employee_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `employee_id` | `String` | Template, Required | The ID of the role to modify. | +| `body` | [`V1 Employee Hash`](/doc/models/v1-employee.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Employee Hash`](/doc/models/v1-employee.md) + +### Example Usage + +```ruby +employee_id = 'employee_id0' +body = {} +body[:first_name] = 'first_name6' +body[:last_name] = 'last_name4' + +result = v1_employees_api.update_employee(employee_id: employee_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Employee Roles + +Provides summary information for all of a business's employee roles. + +```ruby +def list_employee_roles(order: nil, + limit: nil, + batch_token: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which employees are listed in the response, based on their created_at field.Default value: ASC | +| `limit` | `Integer` | Query, Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | +| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Response Type + +[`Array`](/doc/models/v1-employee-role.md) + +### Example Usage + +```ruby +result = v1_employees_api.list_employee_roles() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Employee Role + +Creates an employee role you can then assign to employees. + +Square accounts can include any number of roles that can be assigned to +employees. These roles define the actions and permissions granted to an +employee with that role. For example, an employee with a "Shift Manager" +role might be able to issue refunds in Square Point of Sale, whereas an +employee with a "Clerk" role might not. + +Roles are assigned with the [V1UpdateEmployee](#endpoint-v1updateemployee) +endpoint. An employee can have only one role at a time. + +If an employee has no role, they have none of the permissions associated +with roles. All employees can accept payments with Square Point of Sale. + +```ruby +def create_employee_role(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) | Body, Required | An EmployeeRole object with a name and permissions, and an optional owner flag. | + +### Response Type + +[`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) + +### Example Usage + +```ruby +body = {} +body[:name] = 'name6' +body[:permissions] = ['REGISTER_APPLY_RESTRICTED_DISCOUNTS', 'REGISTER_CHANGE_SETTINGS', 'REGISTER_EDIT_ITEM'] + +result = v1_employees_api.create_employee_role(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Employee Role + +Provides the details for a single employee role. + +```ruby +def retrieve_employee_role(role_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `role_id` | `String` | Template, Required | The role's ID. | + +### Response Type + +[`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) + +### Example Usage + +```ruby +role_id = 'role_id6' + +result = v1_employees_api.retrieve_employee_role(role_id: role_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Employee Role + +Modifies the details of an employee role. + +```ruby +def update_employee_role(role_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `role_id` | `String` | Template, Required | The ID of the role to modify. | +| `body` | [`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Employee Role Hash`](/doc/models/v1-employee-role.md) + +### Example Usage + +```ruby +role_id = 'role_id6' +body = {} +body[:name] = 'name6' +body[:permissions] = ['REGISTER_APPLY_RESTRICTED_DISCOUNTS', 'REGISTER_CHANGE_SETTINGS', 'REGISTER_EDIT_ITEM'] + +result = v1_employees_api.update_employee_role(role_id: role_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Timecards + +Provides summary information for all of a business's employee timecards. + +```ruby +def list_timecards(order: nil, + employee_id: nil, + begin_clockin_time: nil, + end_clockin_time: nil, + begin_clockout_time: nil, + end_clockout_time: nil, + begin_updated_at: nil, + end_updated_at: nil, + deleted: nil, + limit: nil, + batch_token: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which timecards are listed in the response, based on their created_at field. | +| `employee_id` | `String` | Query, Optional | If provided, the endpoint returns only timecards for the employee with the specified ID. | +| `begin_clockin_time` | `String` | Query, Optional | If filtering results by their clockin_time field, the beginning of the requested reporting period, in ISO 8601 format. | +| `end_clockin_time` | `String` | Query, Optional | If filtering results by their clockin_time field, the end of the requested reporting period, in ISO 8601 format. | +| `begin_clockout_time` | `String` | Query, Optional | If filtering results by their clockout_time field, the beginning of the requested reporting period, in ISO 8601 format. | +| `end_clockout_time` | `String` | Query, Optional | If filtering results by their clockout_time field, the end of the requested reporting period, in ISO 8601 format. | +| `begin_updated_at` | `String` | Query, Optional | If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format. | +| `end_updated_at` | `String` | Query, Optional | If filtering results by their updated_at field, the end of the requested reporting period, in ISO 8601 format. | +| `deleted` | `Boolean` | Query, Optional | If true, only deleted timecards are returned. If false, only valid timecards are returned.If you don't provide this parameter, both valid and deleted timecards are returned. | +| `limit` | `Integer` | Query, Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. | +| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Response Type + +[`Array`](/doc/models/v1-timecard.md) + +### Example Usage + +```ruby +result = v1_employees_api.list_timecards() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Timecard + +Creates a timecard for an employee and clocks them in with an +`API_CREATE` event and a `clockin_time` set to the current time unless +the request provides a different value. To import timecards from another +system (rather than clocking someone in). Specify the `clockin_time` +and* `clockout_time` in the request. + +Timecards correspond to exactly one shift for a given employee, bounded +by the `clockin_time` and `clockout_time` fields. An employee is +considered clocked in if they have a timecard that doesn't have a +`clockout_time` set. An employee that is currently clocked in cannot +be clocked in a second time. + +```ruby +def create_timecard(body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`V1 Timecard Hash`](/doc/models/v1-timecard.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Timecard Hash`](/doc/models/v1-timecard.md) + +### Example Usage + +```ruby +body = {} +body[:employee_id] = 'employee_id4' + +result = v1_employees_api.create_timecard(body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Timecard + +Deletes a timecard. Timecards can also be deleted through the +Square Dashboard. Deleted timecards are still accessible through +Connect API endpoints, but cannot be modified. The `deleted` field of +the `Timecard` object indicates whether the timecard has been deleted. + +*Note**: By default, deleted timecards appear alongside valid timecards in +results returned by the [ListTimecards](#endpoint-v1employees-listtimecards) +endpoint. To filter deleted timecards, include the `deleted` query +parameter in the list request. + + + +```ruby +def delete_timecard(timecard_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `timecard_id` | `String` | Template, Required | The ID of the timecard to delete. | + +### Response Type + +`Object` + +### Example Usage + +```ruby +timecard_id = 'timecard_id0' + +result = v1_employees_api.delete_timecard(timecard_id: timecard_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Timecard + +Provides the details for a single timecard. + + +```ruby +def retrieve_timecard(timecard_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `timecard_id` | `String` | Template, Required | The timecard's ID. | + +### Response Type + +[`V1 Timecard Hash`](/doc/models/v1-timecard.md) + +### Example Usage + +```ruby +timecard_id = 'timecard_id0' + +result = v1_employees_api.retrieve_timecard(timecard_id: timecard_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Timecard + +Modifies the details of a timecard with an `API_EDIT` event for +the timecard. Updating an active timecard with a `clockout_time` +clocks the employee out. + +```ruby +def update_timecard(timecard_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `timecard_id` | `String` | Template, Required | TThe ID of the timecard to modify. | +| `body` | [`V1 Timecard Hash`](/doc/models/v1-timecard.md) | Body, Required | An object containing the fields to POST for the request.
See the corresponding object definition for field details. | + +### Response Type + +[`V1 Timecard Hash`](/doc/models/v1-timecard.md) + +### Example Usage + +```ruby +timecard_id = 'timecard_id0' +body = {} +body[:employee_id] = 'employee_id4' + +result = v1_employees_api.update_timecard(timecard_id: timecard_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Timecard Events + +Provides summary information for all events associated with a +particular timecard. + + + +```ruby +def list_timecard_events(timecard_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `timecard_id` | `String` | Template, Required | The ID of the timecard to list events for. | + +### Response Type + +[`Array`](/doc/models/v1-timecard-event.md) + +### Example Usage + +```ruby +timecard_id = 'timecard_id0' + +result = v1_employees_api.list_timecard_events(timecard_id: timecard_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Cash Drawer Shifts + +Provides the details for all of a location's cash drawer shifts during a date range. The date range you specify cannot exceed 90 days. + +```ruby +def list_cash_drawer_shifts(location_id:, + order: nil, + begin_time: nil, + end_time: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list cash drawer shifts for. | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which cash drawer shifts are listed in the response, based on their created_at field. Default value: ASC | +| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time minus 90 days. | +| `end_time` | `String` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time. | + +### Response Type + +[`Array`](/doc/models/v1-cash-drawer-shift.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_employees_api.list_cash_drawer_shifts(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Cash Drawer Shift + +Provides the details for a single cash drawer shift, including all events that occurred during the shift. + +```ruby +def retrieve_cash_drawer_shift(location_id:, + shift_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list cash drawer shifts for. | +| `shift_id` | `String` | Template, Required | The shift's ID. | + +### Response Type + +[`V1 Cash Drawer Shift Hash`](/doc/models/v1-cash-drawer-shift.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +shift_id = 'shift_id0' + +result = v1_employees_api.retrieve_cash_drawer_shift(location_id: location_id, shift_id: shift_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/v1-items.md b/doc/v1-items.md index 16204501..bc1cf475 100644 --- a/doc/v1-items.md +++ b/doc/v1-items.md @@ -1,1542 +1,1542 @@ -# V1 Items - -```ruby -v1_items_api = client.v1_items -``` - -## Class Name - -`V1ItemsApi` - -## Methods - -* [List Categories](/doc/v1-items.md#list-categories) -* [Create Category](/doc/v1-items.md#create-category) -* [Delete Category](/doc/v1-items.md#delete-category) -* [Update Category](/doc/v1-items.md#update-category) -* [List Discounts](/doc/v1-items.md#list-discounts) -* [Create Discount](/doc/v1-items.md#create-discount) -* [Delete Discount](/doc/v1-items.md#delete-discount) -* [Update Discount](/doc/v1-items.md#update-discount) -* [List Fees](/doc/v1-items.md#list-fees) -* [Create Fee](/doc/v1-items.md#create-fee) -* [Delete Fee](/doc/v1-items.md#delete-fee) -* [Update Fee](/doc/v1-items.md#update-fee) -* [List Inventory](/doc/v1-items.md#list-inventory) -* [Adjust Inventory](/doc/v1-items.md#adjust-inventory) -* [List Items](/doc/v1-items.md#list-items) -* [Create Item](/doc/v1-items.md#create-item) -* [Delete Item](/doc/v1-items.md#delete-item) -* [Retrieve Item](/doc/v1-items.md#retrieve-item) -* [Update Item](/doc/v1-items.md#update-item) -* [Remove Fee](/doc/v1-items.md#remove-fee) -* [Apply Fee](/doc/v1-items.md#apply-fee) -* [Remove Modifier List](/doc/v1-items.md#remove-modifier-list) -* [Apply Modifier List](/doc/v1-items.md#apply-modifier-list) -* [Create Variation](/doc/v1-items.md#create-variation) -* [Delete Variation](/doc/v1-items.md#delete-variation) -* [Update Variation](/doc/v1-items.md#update-variation) -* [List Modifier Lists](/doc/v1-items.md#list-modifier-lists) -* [Create Modifier List](/doc/v1-items.md#create-modifier-list) -* [Delete Modifier List](/doc/v1-items.md#delete-modifier-list) -* [Retrieve Modifier List](/doc/v1-items.md#retrieve-modifier-list) -* [Update Modifier List](/doc/v1-items.md#update-modifier-list) -* [Create Modifier Option](/doc/v1-items.md#create-modifier-option) -* [Delete Modifier Option](/doc/v1-items.md#delete-modifier-option) -* [Update Modifier Option](/doc/v1-items.md#update-modifier-option) -* [List Pages](/doc/v1-items.md#list-pages) -* [Create Page](/doc/v1-items.md#create-page) -* [Delete Page](/doc/v1-items.md#delete-page) -* [Update Page](/doc/v1-items.md#update-page) -* [Delete Page Cell](/doc/v1-items.md#delete-page-cell) -* [Update Page Cell](/doc/v1-items.md#update-page-cell) - -## List Categories - -Lists all of a location's item categories. - -```ruby -def list_categories(location_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list categories for. | - -### Response Type - -[`Array`](/doc/models/v1-category.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_items_api.list_categories(location_id: location_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Category - -Creates an item category. - -```ruby -def create_category(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to create an item for. | -| `body` | [`V1 Category Hash`](/doc/models/v1-category.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Category Hash`](/doc/models/v1-category.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} - -result = v1_items_api.create_category(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Category - -Deletes an existing item category. -*Note**: DeleteCategory returns nothing on success but Connect SDKs -map the empty response to an empty `V1DeleteCategoryRequest` object -as documented below. - -```ruby -def delete_category(location_id:, - category_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `category_id` | `String` | Template, Required | The ID of the category to delete. | - -### Response Type - -[`V1 Category Hash`](/doc/models/v1-category.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -category_id = 'category_id8' - -result = v1_items_api.delete_category(location_id: location_id, category_id: category_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Category - -Modifies the details of an existing item category. - -```ruby -def update_category(location_id:, - category_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the category's associated location. | -| `category_id` | `String` | Template, Required | The ID of the category to edit. | -| `body` | [`V1 Category Hash`](/doc/models/v1-category.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Category Hash`](/doc/models/v1-category.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -category_id = 'category_id8' -body = {} - -result = v1_items_api.update_category(location_id: location_id, category_id: category_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Discounts - -Lists all of a location's discounts. - -```ruby -def list_discounts(location_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list categories for. | - -### Response Type - -[`Array`](/doc/models/v1-discount.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_items_api.list_discounts(location_id: location_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Discount - -Creates a discount. - -```ruby -def create_discount(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to create an item for. | -| `body` | [`V1 Discount Hash`](/doc/models/v1-discount.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Discount Hash`](/doc/models/v1-discount.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} - -result = v1_items_api.create_discount(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Discount - -Deletes an existing discount. -*Note**: DeleteDiscount returns nothing on success but Connect SDKs -map the empty response to an empty `V1DeleteDiscountRequest` object -as documented below. - -```ruby -def delete_discount(location_id:, - discount_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `discount_id` | `String` | Template, Required | The ID of the discount to delete. | - -### Response Type - -[`V1 Discount Hash`](/doc/models/v1-discount.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -discount_id = 'discount_id8' - -result = v1_items_api.delete_discount(location_id: location_id, discount_id: discount_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Discount - -Modifies the details of an existing discount. - -```ruby -def update_discount(location_id:, - discount_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the category's associated location. | -| `discount_id` | `String` | Template, Required | The ID of the discount to edit. | -| `body` | [`V1 Discount Hash`](/doc/models/v1-discount.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Discount Hash`](/doc/models/v1-discount.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -discount_id = 'discount_id8' -body = {} - -result = v1_items_api.update_discount(location_id: location_id, discount_id: discount_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Fees - -Lists all of a location's fees (taxes). - -```ruby -def list_fees(location_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list fees for. | - -### Response Type - -[`Array`](/doc/models/v1-fee.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_items_api.list_fees(location_id: location_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Fee - -Creates a fee (tax). - -```ruby -def create_fee(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to create a fee for. | -| `body` | [`V1 Fee Hash`](/doc/models/v1-fee.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Fee Hash`](/doc/models/v1-fee.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} - -result = v1_items_api.create_fee(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Fee - -Deletes an existing fee (tax). -*Note**: DeleteFee returns nothing on success but Connect SDKs -map the empty response to an empty `V1DeleteFeeRequest` object -as documented below. - -```ruby -def delete_fee(location_id:, - fee_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the fee's associated location. | -| `fee_id` | `String` | Template, Required | The ID of the fee to delete. | - -### Response Type - -[`V1 Fee Hash`](/doc/models/v1-fee.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -fee_id = 'fee_id8' - -result = v1_items_api.delete_fee(location_id: location_id, fee_id: fee_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Fee - -Modifies the details of an existing fee (tax). - -```ruby -def update_fee(location_id:, - fee_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the fee's associated location. | -| `fee_id` | `String` | Template, Required | The ID of the fee to edit. | -| `body` | [`V1 Fee Hash`](/doc/models/v1-fee.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Fee Hash`](/doc/models/v1-fee.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -fee_id = 'fee_id8' -body = {} - -result = v1_items_api.update_fee(location_id: location_id, fee_id: fee_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Inventory - -Provides inventory information for all of a merchant's inventory-enabled item variations. - -```ruby -def list_inventory(location_id:, - limit: nil, - batch_token: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `limit` | `Integer` | Query, Optional | The maximum number of inventory entries to return in a single response. This value cannot exceed 1000. | -| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Response Type - -[`Array`](/doc/models/v1-inventory-entry.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_items_api.list_inventory(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Adjust Inventory - -Adjusts an item variation's current available inventory. - -```ruby -def adjust_inventory(location_id:, - variation_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `variation_id` | `String` | Template, Required | The ID of the variation to adjust inventory information for. | -| `body` | [`V1 Adjust Inventory Request Hash`](/doc/models/v1-adjust-inventory-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Inventory Entry Hash`](/doc/models/v1-inventory-entry.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -variation_id = 'variation_id2' -body = {} - -result = v1_items_api.adjust_inventory(location_id: location_id, variation_id: variation_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Items - -Provides summary information for all of a location's items. - -```ruby -def list_items(location_id:, - batch_token: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list items for. | -| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Response Type - -[`Array`](/doc/models/v1-item.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_items_api.list_items(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Item - -Creates an item and at least one variation for it. Item-related -entities include fields you can use to associate them with entities in a -non-Square system. - -When you create an item-related entity, you can optionally specify its -`id`. This value must be unique among all IDs ever specified for the -account, including those specified by other applications. You can never -reuse an entity ID. If you do not specify an ID, Square generates one -for the entity. - -Item variations have a `user_data` string that lets you associate -arbitrary metadata with the variation. The string cannot exceed 255 -characters. - -```ruby -def create_item(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to create an item for. | -| `body` | [`V1 Item Hash`](/doc/models/v1-item.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Item Hash`](/doc/models/v1-item.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} - -result = v1_items_api.create_item(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Item - -Deletes an existing item and all item variations associated with it. -*Note**: DeleteItem returns nothing on success but Connect SDKs -map the empty response to an empty `V1DeleteItemRequest` object -as documented below. - -```ruby -def delete_item(location_id:, - item_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `item_id` | `String` | Template, Required | The ID of the item to modify. | - -### Response Type - -[`V1 Item Hash`](/doc/models/v1-item.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -item_id = 'item_id0' - -result = v1_items_api.delete_item(location_id: location_id, item_id: item_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Item - -Provides the details for a single item, including associated modifier lists and fees. - -```ruby -def retrieve_item(location_id:, - item_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `item_id` | `String` | Template, Required | The item's ID. | - -### Response Type - -[`V1 Item Hash`](/doc/models/v1-item.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -item_id = 'item_id0' - -result = v1_items_api.retrieve_item(location_id: location_id, item_id: item_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Item - -Modifies the core details of an existing item. - -```ruby -def update_item(location_id:, - item_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `item_id` | `String` | Template, Required | The ID of the item to modify. | -| `body` | [`V1 Item Hash`](/doc/models/v1-item.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Item Hash`](/doc/models/v1-item.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -item_id = 'item_id0' -body = {} - -result = v1_items_api.update_item(location_id: location_id, item_id: item_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Remove Fee - -Removes a fee assocation from an item, meaning the fee is no longer automatically applied to the item in Square Register. - -```ruby -def remove_fee(location_id:, - item_id:, - fee_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the fee's associated location. | -| `item_id` | `String` | Template, Required | The ID of the item to add the fee to. | -| `fee_id` | `String` | Template, Required | The ID of the fee to apply. | - -### Response Type - -[`V1 Item Hash`](/doc/models/v1-item.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -item_id = 'item_id0' -fee_id = 'fee_id8' - -result = v1_items_api.remove_fee(location_id: location_id, item_id: item_id, fee_id: fee_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Apply Fee - -Associates a fee with an item, meaning the fee is automatically applied to the item in Square Register. - -```ruby -def apply_fee(location_id:, - item_id:, - fee_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the fee's associated location. | -| `item_id` | `String` | Template, Required | The ID of the item to add the fee to. | -| `fee_id` | `String` | Template, Required | The ID of the fee to apply. | - -### Response Type - -[`V1 Item Hash`](/doc/models/v1-item.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -item_id = 'item_id0' -fee_id = 'fee_id8' - -result = v1_items_api.apply_fee(location_id: location_id, item_id: item_id, fee_id: fee_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Remove Modifier List - -Removes a modifier list association from an item, meaning modifier options from the list can no longer be applied to the item. - -```ruby -def remove_modifier_list(location_id:, - modifier_list_id:, - item_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to remove. | -| `item_id` | `String` | Template, Required | The ID of the item to remove the modifier list from. | - -### Response Type - -[`V1 Item Hash`](/doc/models/v1-item.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -modifier_list_id = 'modifier_list_id6' -item_id = 'item_id0' - -result = v1_items_api.remove_modifier_list(location_id: location_id, modifier_list_id: modifier_list_id, item_id: item_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Apply Modifier List - -Associates a modifier list with an item, meaning modifier options from the list can be applied to the item. - -```ruby -def apply_modifier_list(location_id:, - modifier_list_id:, - item_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to apply. | -| `item_id` | `String` | Template, Required | The ID of the item to add the modifier list to. | - -### Response Type - -[`V1 Item Hash`](/doc/models/v1-item.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -modifier_list_id = 'modifier_list_id6' -item_id = 'item_id0' - -result = v1_items_api.apply_modifier_list(location_id: location_id, modifier_list_id: modifier_list_id, item_id: item_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Variation - -Creates an item variation for an existing item. - -```ruby -def create_variation(location_id:, - item_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `item_id` | `String` | Template, Required | The item's ID. | -| `body` | [`V1 Variation Hash`](/doc/models/v1-variation.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Variation Hash`](/doc/models/v1-variation.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -item_id = 'item_id0' -body = {} - -result = v1_items_api.create_variation(location_id: location_id, item_id: item_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Variation - -Deletes an existing item variation from an item. -*Note**: DeleteVariation returns nothing on success but Connect SDKs -map the empty response to an empty `V1DeleteVariationRequest` object -as documented below. - -```ruby -def delete_variation(location_id:, - item_id:, - variation_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `item_id` | `String` | Template, Required | The ID of the item to delete. | -| `variation_id` | `String` | Template, Required | The ID of the variation to delete. | - -### Response Type - -[`V1 Variation Hash`](/doc/models/v1-variation.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -item_id = 'item_id0' -variation_id = 'variation_id2' - -result = v1_items_api.delete_variation(location_id: location_id, item_id: item_id, variation_id: variation_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Variation - -Modifies the details of an existing item variation. - -```ruby -def update_variation(location_id:, - item_id:, - variation_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `item_id` | `String` | Template, Required | The ID of the item to modify. | -| `variation_id` | `String` | Template, Required | The ID of the variation to modify. | -| `body` | [`V1 Variation Hash`](/doc/models/v1-variation.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Variation Hash`](/doc/models/v1-variation.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -item_id = 'item_id0' -variation_id = 'variation_id2' -body = {} - -result = v1_items_api.update_variation(location_id: location_id, item_id: item_id, variation_id: variation_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Modifier Lists - -Lists all of a location's modifier lists. - -```ruby -def list_modifier_lists(location_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list modifier lists for. | - -### Response Type - -[`Array`](/doc/models/v1-modifier-list.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_items_api.list_modifier_lists(location_id: location_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Modifier List - -Creates an item modifier list and at least one modifier option for it. - -```ruby -def create_modifier_list(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to create a modifier list for. | -| `body` | [`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} - -result = v1_items_api.create_modifier_list(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Modifier List - -Deletes an existing item modifier list and all modifier options -associated with it. -*Note**: DeleteModifierList returns nothing on success but Connect SDKs -map the empty response to an empty `V1DeleteModifierListRequest` object -as documented below. - -```ruby -def delete_modifier_list(location_id:, - modifier_list_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to delete. | - -### Response Type - -[`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -modifier_list_id = 'modifier_list_id6' - -result = v1_items_api.delete_modifier_list(location_id: location_id, modifier_list_id: modifier_list_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Modifier List - -Provides the details for a single modifier list. - -```ruby -def retrieve_modifier_list(location_id:, - modifier_list_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `modifier_list_id` | `String` | Template, Required | The modifier list's ID. | - -### Response Type - -[`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -modifier_list_id = 'modifier_list_id6' - -result = v1_items_api.retrieve_modifier_list(location_id: location_id, modifier_list_id: modifier_list_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Modifier List - -Modifies the details of an existing item modifier list. - -```ruby -def update_modifier_list(location_id:, - modifier_list_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to edit. | -| `body` | [`V1 Update Modifier List Request Hash`](/doc/models/v1-update-modifier-list-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -modifier_list_id = 'modifier_list_id6' -body = {} - -result = v1_items_api.update_modifier_list(location_id: location_id, modifier_list_id: modifier_list_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Modifier Option - -Creates an item modifier option and adds it to a modifier list. - -```ruby -def create_modifier_option(location_id:, - modifier_list_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to edit. | -| `body` | [`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -modifier_list_id = 'modifier_list_id6' -body = {} - -result = v1_items_api.create_modifier_option(location_id: location_id, modifier_list_id: modifier_list_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Modifier Option - -Deletes an existing item modifier option from a modifier list. -*Note**: DeleteModifierOption returns nothing on success but Connect SDKs -map the empty response to an empty `V1DeleteModifierOptionRequest` object -as documented below. - -```ruby -def delete_modifier_option(location_id:, - modifier_list_id:, - modifier_option_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to delete. | -| `modifier_option_id` | `String` | Template, Required | The ID of the modifier list to edit. | - -### Response Type - -[`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -modifier_list_id = 'modifier_list_id6' -modifier_option_id = 'modifier_option_id6' - -result = v1_items_api.delete_modifier_option(location_id: location_id, modifier_list_id: modifier_list_id, modifier_option_id: modifier_option_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Modifier Option - -Modifies the details of an existing item modifier option. - -```ruby -def update_modifier_option(location_id:, - modifier_list_id:, - modifier_option_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the item's associated location. | -| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to edit. | -| `modifier_option_id` | `String` | Template, Required | The ID of the modifier list to edit. | -| `body` | [`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -modifier_list_id = 'modifier_list_id6' -modifier_option_id = 'modifier_option_id6' -body = {} - -result = v1_items_api.update_modifier_option(location_id: location_id, modifier_list_id: modifier_list_id, modifier_option_id: modifier_option_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Pages - -Lists all of a location's Favorites pages in Square Register. - -```ruby -def list_pages(location_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list Favorites pages for. | - -### Response Type - -[`Array`](/doc/models/v1-page.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_items_api.list_pages(location_id: location_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Page - -Creates a Favorites page in Square Register. - -```ruby -def create_page(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to create an item for. | -| `body` | [`V1 Page Hash`](/doc/models/v1-page.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Page Hash`](/doc/models/v1-page.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} - -result = v1_items_api.create_page(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Page - -Deletes an existing Favorites page and all of its cells. -*Note**: DeletePage returns nothing on success but Connect SDKs -map the empty response to an empty `V1DeletePageRequest` object -as documented below. - -```ruby -def delete_page(location_id:, - page_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the Favorites page's associated location. | -| `page_id` | `String` | Template, Required | The ID of the page to delete. | - -### Response Type - -[`V1 Page Hash`](/doc/models/v1-page.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -page_id = 'page_id0' - -result = v1_items_api.delete_page(location_id: location_id, page_id: page_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Page - -Modifies the details of a Favorites page in Square Register. - -```ruby -def update_page(location_id:, - page_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the Favorites page's associated location | -| `page_id` | `String` | Template, Required | The ID of the page to modify. | -| `body` | [`V1 Page Hash`](/doc/models/v1-page.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Page Hash`](/doc/models/v1-page.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -page_id = 'page_id0' -body = {} - -result = v1_items_api.update_page(location_id: location_id, page_id: page_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Delete Page Cell - -Deletes a cell from a Favorites page in Square Register. -*Note**: DeletePageCell returns nothing on success but Connect SDKs -map the empty response to an empty `V1DeletePageCellRequest` object -as documented below. - -```ruby -def delete_page_cell(location_id:, - page_id:, - row: nil, - column: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the Favorites page's associated location. | -| `page_id` | `String` | Template, Required | The ID of the page to delete. | -| `row` | `String` | Query, Optional | The row of the cell to clear. Always an integer between 0 and 4, inclusive. Row 0 is the top row. | -| `column` | `String` | Query, Optional | The column of the cell to clear. Always an integer between 0 and 4, inclusive. Column 0 is the leftmost column. | - -### Response Type - -[`V1 Page Hash`](/doc/models/v1-page.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -page_id = 'page_id0' - -result = v1_items_api.delete_page_cell(location_id: location_id, page_id: page_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Page Cell - -Modifies a cell of a Favorites page in Square Register. - -```ruby -def update_page_cell(location_id:, - page_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the Favorites page's associated location. | -| `page_id` | `String` | Template, Required | The ID of the page the cell belongs to. | -| `body` | [`V1 Page Cell Hash`](/doc/models/v1-page-cell.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Page Hash`](/doc/models/v1-page.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -page_id = 'page_id0' -body = {} - -result = v1_items_api.update_page_cell(location_id: location_id, page_id: page_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# V1 Items + +```ruby +v1_items_api = client.v1_items +``` + +## Class Name + +`V1ItemsApi` + +## Methods + +* [List Categories](/doc/v1-items.md#list-categories) +* [Create Category](/doc/v1-items.md#create-category) +* [Delete Category](/doc/v1-items.md#delete-category) +* [Update Category](/doc/v1-items.md#update-category) +* [List Discounts](/doc/v1-items.md#list-discounts) +* [Create Discount](/doc/v1-items.md#create-discount) +* [Delete Discount](/doc/v1-items.md#delete-discount) +* [Update Discount](/doc/v1-items.md#update-discount) +* [List Fees](/doc/v1-items.md#list-fees) +* [Create Fee](/doc/v1-items.md#create-fee) +* [Delete Fee](/doc/v1-items.md#delete-fee) +* [Update Fee](/doc/v1-items.md#update-fee) +* [List Inventory](/doc/v1-items.md#list-inventory) +* [Adjust Inventory](/doc/v1-items.md#adjust-inventory) +* [List Items](/doc/v1-items.md#list-items) +* [Create Item](/doc/v1-items.md#create-item) +* [Delete Item](/doc/v1-items.md#delete-item) +* [Retrieve Item](/doc/v1-items.md#retrieve-item) +* [Update Item](/doc/v1-items.md#update-item) +* [Remove Fee](/doc/v1-items.md#remove-fee) +* [Apply Fee](/doc/v1-items.md#apply-fee) +* [Remove Modifier List](/doc/v1-items.md#remove-modifier-list) +* [Apply Modifier List](/doc/v1-items.md#apply-modifier-list) +* [Create Variation](/doc/v1-items.md#create-variation) +* [Delete Variation](/doc/v1-items.md#delete-variation) +* [Update Variation](/doc/v1-items.md#update-variation) +* [List Modifier Lists](/doc/v1-items.md#list-modifier-lists) +* [Create Modifier List](/doc/v1-items.md#create-modifier-list) +* [Delete Modifier List](/doc/v1-items.md#delete-modifier-list) +* [Retrieve Modifier List](/doc/v1-items.md#retrieve-modifier-list) +* [Update Modifier List](/doc/v1-items.md#update-modifier-list) +* [Create Modifier Option](/doc/v1-items.md#create-modifier-option) +* [Delete Modifier Option](/doc/v1-items.md#delete-modifier-option) +* [Update Modifier Option](/doc/v1-items.md#update-modifier-option) +* [List Pages](/doc/v1-items.md#list-pages) +* [Create Page](/doc/v1-items.md#create-page) +* [Delete Page](/doc/v1-items.md#delete-page) +* [Update Page](/doc/v1-items.md#update-page) +* [Delete Page Cell](/doc/v1-items.md#delete-page-cell) +* [Update Page Cell](/doc/v1-items.md#update-page-cell) + +## List Categories + +Lists all of a location's item categories. + +```ruby +def list_categories(location_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list categories for. | + +### Response Type + +[`Array`](/doc/models/v1-category.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_items_api.list_categories(location_id: location_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Category + +Creates an item category. + +```ruby +def create_category(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to create an item for. | +| `body` | [`V1 Category Hash`](/doc/models/v1-category.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Category Hash`](/doc/models/v1-category.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} + +result = v1_items_api.create_category(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Category + +Deletes an existing item category. +*Note**: DeleteCategory returns nothing on success but Connect SDKs +map the empty response to an empty `V1DeleteCategoryRequest` object +as documented below. + +```ruby +def delete_category(location_id:, + category_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `category_id` | `String` | Template, Required | The ID of the category to delete. | + +### Response Type + +[`V1 Category Hash`](/doc/models/v1-category.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +category_id = 'category_id8' + +result = v1_items_api.delete_category(location_id: location_id, category_id: category_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Category + +Modifies the details of an existing item category. + +```ruby +def update_category(location_id:, + category_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the category's associated location. | +| `category_id` | `String` | Template, Required | The ID of the category to edit. | +| `body` | [`V1 Category Hash`](/doc/models/v1-category.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Category Hash`](/doc/models/v1-category.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +category_id = 'category_id8' +body = {} + +result = v1_items_api.update_category(location_id: location_id, category_id: category_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Discounts + +Lists all of a location's discounts. + +```ruby +def list_discounts(location_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list categories for. | + +### Response Type + +[`Array`](/doc/models/v1-discount.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_items_api.list_discounts(location_id: location_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Discount + +Creates a discount. + +```ruby +def create_discount(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to create an item for. | +| `body` | [`V1 Discount Hash`](/doc/models/v1-discount.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Discount Hash`](/doc/models/v1-discount.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} + +result = v1_items_api.create_discount(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Discount + +Deletes an existing discount. +*Note**: DeleteDiscount returns nothing on success but Connect SDKs +map the empty response to an empty `V1DeleteDiscountRequest` object +as documented below. + +```ruby +def delete_discount(location_id:, + discount_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `discount_id` | `String` | Template, Required | The ID of the discount to delete. | + +### Response Type + +[`V1 Discount Hash`](/doc/models/v1-discount.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +discount_id = 'discount_id8' + +result = v1_items_api.delete_discount(location_id: location_id, discount_id: discount_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Discount + +Modifies the details of an existing discount. + +```ruby +def update_discount(location_id:, + discount_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the category's associated location. | +| `discount_id` | `String` | Template, Required | The ID of the discount to edit. | +| `body` | [`V1 Discount Hash`](/doc/models/v1-discount.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Discount Hash`](/doc/models/v1-discount.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +discount_id = 'discount_id8' +body = {} + +result = v1_items_api.update_discount(location_id: location_id, discount_id: discount_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Fees + +Lists all of a location's fees (taxes). + +```ruby +def list_fees(location_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list fees for. | + +### Response Type + +[`Array`](/doc/models/v1-fee.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_items_api.list_fees(location_id: location_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Fee + +Creates a fee (tax). + +```ruby +def create_fee(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to create a fee for. | +| `body` | [`V1 Fee Hash`](/doc/models/v1-fee.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Fee Hash`](/doc/models/v1-fee.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} + +result = v1_items_api.create_fee(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Fee + +Deletes an existing fee (tax). +*Note**: DeleteFee returns nothing on success but Connect SDKs +map the empty response to an empty `V1DeleteFeeRequest` object +as documented below. + +```ruby +def delete_fee(location_id:, + fee_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the fee's associated location. | +| `fee_id` | `String` | Template, Required | The ID of the fee to delete. | + +### Response Type + +[`V1 Fee Hash`](/doc/models/v1-fee.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +fee_id = 'fee_id8' + +result = v1_items_api.delete_fee(location_id: location_id, fee_id: fee_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Fee + +Modifies the details of an existing fee (tax). + +```ruby +def update_fee(location_id:, + fee_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the fee's associated location. | +| `fee_id` | `String` | Template, Required | The ID of the fee to edit. | +| `body` | [`V1 Fee Hash`](/doc/models/v1-fee.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Fee Hash`](/doc/models/v1-fee.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +fee_id = 'fee_id8' +body = {} + +result = v1_items_api.update_fee(location_id: location_id, fee_id: fee_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Inventory + +Provides inventory information for all of a merchant's inventory-enabled item variations. + +```ruby +def list_inventory(location_id:, + limit: nil, + batch_token: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `limit` | `Integer` | Query, Optional | The maximum number of inventory entries to return in a single response. This value cannot exceed 1000. | +| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Response Type + +[`Array`](/doc/models/v1-inventory-entry.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_items_api.list_inventory(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Adjust Inventory + +Adjusts an item variation's current available inventory. + +```ruby +def adjust_inventory(location_id:, + variation_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `variation_id` | `String` | Template, Required | The ID of the variation to adjust inventory information for. | +| `body` | [`V1 Adjust Inventory Request Hash`](/doc/models/v1-adjust-inventory-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Inventory Entry Hash`](/doc/models/v1-inventory-entry.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +variation_id = 'variation_id2' +body = {} + +result = v1_items_api.adjust_inventory(location_id: location_id, variation_id: variation_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Items + +Provides summary information for all of a location's items. + +```ruby +def list_items(location_id:, + batch_token: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list items for. | +| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Response Type + +[`Array`](/doc/models/v1-item.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_items_api.list_items(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Item + +Creates an item and at least one variation for it. Item-related +entities include fields you can use to associate them with entities in a +non-Square system. + +When you create an item-related entity, you can optionally specify its +`id`. This value must be unique among all IDs ever specified for the +account, including those specified by other applications. You can never +reuse an entity ID. If you do not specify an ID, Square generates one +for the entity. + +Item variations have a `user_data` string that lets you associate +arbitrary metadata with the variation. The string cannot exceed 255 +characters. + +```ruby +def create_item(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to create an item for. | +| `body` | [`V1 Item Hash`](/doc/models/v1-item.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Item Hash`](/doc/models/v1-item.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} + +result = v1_items_api.create_item(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Item + +Deletes an existing item and all item variations associated with it. +*Note**: DeleteItem returns nothing on success but Connect SDKs +map the empty response to an empty `V1DeleteItemRequest` object +as documented below. + +```ruby +def delete_item(location_id:, + item_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `item_id` | `String` | Template, Required | The ID of the item to modify. | + +### Response Type + +[`V1 Item Hash`](/doc/models/v1-item.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +item_id = 'item_id0' + +result = v1_items_api.delete_item(location_id: location_id, item_id: item_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Item + +Provides the details for a single item, including associated modifier lists and fees. + +```ruby +def retrieve_item(location_id:, + item_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `item_id` | `String` | Template, Required | The item's ID. | + +### Response Type + +[`V1 Item Hash`](/doc/models/v1-item.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +item_id = 'item_id0' + +result = v1_items_api.retrieve_item(location_id: location_id, item_id: item_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Item + +Modifies the core details of an existing item. + +```ruby +def update_item(location_id:, + item_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `item_id` | `String` | Template, Required | The ID of the item to modify. | +| `body` | [`V1 Item Hash`](/doc/models/v1-item.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Item Hash`](/doc/models/v1-item.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +item_id = 'item_id0' +body = {} + +result = v1_items_api.update_item(location_id: location_id, item_id: item_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Remove Fee + +Removes a fee assocation from an item, meaning the fee is no longer automatically applied to the item in Square Register. + +```ruby +def remove_fee(location_id:, + item_id:, + fee_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the fee's associated location. | +| `item_id` | `String` | Template, Required | The ID of the item to add the fee to. | +| `fee_id` | `String` | Template, Required | The ID of the fee to apply. | + +### Response Type + +[`V1 Item Hash`](/doc/models/v1-item.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +item_id = 'item_id0' +fee_id = 'fee_id8' + +result = v1_items_api.remove_fee(location_id: location_id, item_id: item_id, fee_id: fee_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Apply Fee + +Associates a fee with an item, meaning the fee is automatically applied to the item in Square Register. + +```ruby +def apply_fee(location_id:, + item_id:, + fee_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the fee's associated location. | +| `item_id` | `String` | Template, Required | The ID of the item to add the fee to. | +| `fee_id` | `String` | Template, Required | The ID of the fee to apply. | + +### Response Type + +[`V1 Item Hash`](/doc/models/v1-item.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +item_id = 'item_id0' +fee_id = 'fee_id8' + +result = v1_items_api.apply_fee(location_id: location_id, item_id: item_id, fee_id: fee_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Remove Modifier List + +Removes a modifier list association from an item, meaning modifier options from the list can no longer be applied to the item. + +```ruby +def remove_modifier_list(location_id:, + modifier_list_id:, + item_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to remove. | +| `item_id` | `String` | Template, Required | The ID of the item to remove the modifier list from. | + +### Response Type + +[`V1 Item Hash`](/doc/models/v1-item.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +modifier_list_id = 'modifier_list_id6' +item_id = 'item_id0' + +result = v1_items_api.remove_modifier_list(location_id: location_id, modifier_list_id: modifier_list_id, item_id: item_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Apply Modifier List + +Associates a modifier list with an item, meaning modifier options from the list can be applied to the item. + +```ruby +def apply_modifier_list(location_id:, + modifier_list_id:, + item_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to apply. | +| `item_id` | `String` | Template, Required | The ID of the item to add the modifier list to. | + +### Response Type + +[`V1 Item Hash`](/doc/models/v1-item.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +modifier_list_id = 'modifier_list_id6' +item_id = 'item_id0' + +result = v1_items_api.apply_modifier_list(location_id: location_id, modifier_list_id: modifier_list_id, item_id: item_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Variation + +Creates an item variation for an existing item. + +```ruby +def create_variation(location_id:, + item_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `item_id` | `String` | Template, Required | The item's ID. | +| `body` | [`V1 Variation Hash`](/doc/models/v1-variation.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Variation Hash`](/doc/models/v1-variation.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +item_id = 'item_id0' +body = {} + +result = v1_items_api.create_variation(location_id: location_id, item_id: item_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Variation + +Deletes an existing item variation from an item. +*Note**: DeleteVariation returns nothing on success but Connect SDKs +map the empty response to an empty `V1DeleteVariationRequest` object +as documented below. + +```ruby +def delete_variation(location_id:, + item_id:, + variation_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `item_id` | `String` | Template, Required | The ID of the item to delete. | +| `variation_id` | `String` | Template, Required | The ID of the variation to delete. | + +### Response Type + +[`V1 Variation Hash`](/doc/models/v1-variation.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +item_id = 'item_id0' +variation_id = 'variation_id2' + +result = v1_items_api.delete_variation(location_id: location_id, item_id: item_id, variation_id: variation_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Variation + +Modifies the details of an existing item variation. + +```ruby +def update_variation(location_id:, + item_id:, + variation_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `item_id` | `String` | Template, Required | The ID of the item to modify. | +| `variation_id` | `String` | Template, Required | The ID of the variation to modify. | +| `body` | [`V1 Variation Hash`](/doc/models/v1-variation.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Variation Hash`](/doc/models/v1-variation.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +item_id = 'item_id0' +variation_id = 'variation_id2' +body = {} + +result = v1_items_api.update_variation(location_id: location_id, item_id: item_id, variation_id: variation_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Modifier Lists + +Lists all of a location's modifier lists. + +```ruby +def list_modifier_lists(location_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list modifier lists for. | + +### Response Type + +[`Array`](/doc/models/v1-modifier-list.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_items_api.list_modifier_lists(location_id: location_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Modifier List + +Creates an item modifier list and at least one modifier option for it. + +```ruby +def create_modifier_list(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to create a modifier list for. | +| `body` | [`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} + +result = v1_items_api.create_modifier_list(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Modifier List + +Deletes an existing item modifier list and all modifier options +associated with it. +*Note**: DeleteModifierList returns nothing on success but Connect SDKs +map the empty response to an empty `V1DeleteModifierListRequest` object +as documented below. + +```ruby +def delete_modifier_list(location_id:, + modifier_list_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to delete. | + +### Response Type + +[`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +modifier_list_id = 'modifier_list_id6' + +result = v1_items_api.delete_modifier_list(location_id: location_id, modifier_list_id: modifier_list_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Modifier List + +Provides the details for a single modifier list. + +```ruby +def retrieve_modifier_list(location_id:, + modifier_list_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `modifier_list_id` | `String` | Template, Required | The modifier list's ID. | + +### Response Type + +[`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +modifier_list_id = 'modifier_list_id6' + +result = v1_items_api.retrieve_modifier_list(location_id: location_id, modifier_list_id: modifier_list_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Modifier List + +Modifies the details of an existing item modifier list. + +```ruby +def update_modifier_list(location_id:, + modifier_list_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to edit. | +| `body` | [`V1 Update Modifier List Request Hash`](/doc/models/v1-update-modifier-list-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Modifier List Hash`](/doc/models/v1-modifier-list.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +modifier_list_id = 'modifier_list_id6' +body = {} + +result = v1_items_api.update_modifier_list(location_id: location_id, modifier_list_id: modifier_list_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Modifier Option + +Creates an item modifier option and adds it to a modifier list. + +```ruby +def create_modifier_option(location_id:, + modifier_list_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to edit. | +| `body` | [`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +modifier_list_id = 'modifier_list_id6' +body = {} + +result = v1_items_api.create_modifier_option(location_id: location_id, modifier_list_id: modifier_list_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Modifier Option + +Deletes an existing item modifier option from a modifier list. +*Note**: DeleteModifierOption returns nothing on success but Connect SDKs +map the empty response to an empty `V1DeleteModifierOptionRequest` object +as documented below. + +```ruby +def delete_modifier_option(location_id:, + modifier_list_id:, + modifier_option_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to delete. | +| `modifier_option_id` | `String` | Template, Required | The ID of the modifier list to edit. | + +### Response Type + +[`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +modifier_list_id = 'modifier_list_id6' +modifier_option_id = 'modifier_option_id6' + +result = v1_items_api.delete_modifier_option(location_id: location_id, modifier_list_id: modifier_list_id, modifier_option_id: modifier_option_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Modifier Option + +Modifies the details of an existing item modifier option. + +```ruby +def update_modifier_option(location_id:, + modifier_list_id:, + modifier_option_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the item's associated location. | +| `modifier_list_id` | `String` | Template, Required | The ID of the modifier list to edit. | +| `modifier_option_id` | `String` | Template, Required | The ID of the modifier list to edit. | +| `body` | [`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Modifier Option Hash`](/doc/models/v1-modifier-option.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +modifier_list_id = 'modifier_list_id6' +modifier_option_id = 'modifier_option_id6' +body = {} + +result = v1_items_api.update_modifier_option(location_id: location_id, modifier_list_id: modifier_list_id, modifier_option_id: modifier_option_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Pages + +Lists all of a location's Favorites pages in Square Register. + +```ruby +def list_pages(location_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list Favorites pages for. | + +### Response Type + +[`Array`](/doc/models/v1-page.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_items_api.list_pages(location_id: location_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Page + +Creates a Favorites page in Square Register. + +```ruby +def create_page(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to create an item for. | +| `body` | [`V1 Page Hash`](/doc/models/v1-page.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Page Hash`](/doc/models/v1-page.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} + +result = v1_items_api.create_page(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Page + +Deletes an existing Favorites page and all of its cells. +*Note**: DeletePage returns nothing on success but Connect SDKs +map the empty response to an empty `V1DeletePageRequest` object +as documented below. + +```ruby +def delete_page(location_id:, + page_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the Favorites page's associated location. | +| `page_id` | `String` | Template, Required | The ID of the page to delete. | + +### Response Type + +[`V1 Page Hash`](/doc/models/v1-page.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +page_id = 'page_id0' + +result = v1_items_api.delete_page(location_id: location_id, page_id: page_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Page + +Modifies the details of a Favorites page in Square Register. + +```ruby +def update_page(location_id:, + page_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the Favorites page's associated location | +| `page_id` | `String` | Template, Required | The ID of the page to modify. | +| `body` | [`V1 Page Hash`](/doc/models/v1-page.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Page Hash`](/doc/models/v1-page.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +page_id = 'page_id0' +body = {} + +result = v1_items_api.update_page(location_id: location_id, page_id: page_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Delete Page Cell + +Deletes a cell from a Favorites page in Square Register. +*Note**: DeletePageCell returns nothing on success but Connect SDKs +map the empty response to an empty `V1DeletePageCellRequest` object +as documented below. + +```ruby +def delete_page_cell(location_id:, + page_id:, + row: nil, + column: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the Favorites page's associated location. | +| `page_id` | `String` | Template, Required | The ID of the page to delete. | +| `row` | `String` | Query, Optional | The row of the cell to clear. Always an integer between 0 and 4, inclusive. Row 0 is the top row. | +| `column` | `String` | Query, Optional | The column of the cell to clear. Always an integer between 0 and 4, inclusive. Column 0 is the leftmost column. | + +### Response Type + +[`V1 Page Hash`](/doc/models/v1-page.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +page_id = 'page_id0' + +result = v1_items_api.delete_page_cell(location_id: location_id, page_id: page_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Page Cell + +Modifies a cell of a Favorites page in Square Register. + +```ruby +def update_page_cell(location_id:, + page_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the Favorites page's associated location. | +| `page_id` | `String` | Template, Required | The ID of the page the cell belongs to. | +| `body` | [`V1 Page Cell Hash`](/doc/models/v1-page-cell.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Page Hash`](/doc/models/v1-page.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +page_id = 'page_id0' +body = {} + +result = v1_items_api.update_page_cell(location_id: location_id, page_id: page_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/v1-locations.md b/doc/v1-locations.md index 57ee9752..ab884f09 100644 --- a/doc/v1-locations.md +++ b/doc/v1-locations.md @@ -1,63 +1,63 @@ -# V1 Locations - -```ruby -v1_locations_api = client.v1_locations -``` - -## Class Name - -`V1LocationsApi` - -## Methods - -* [Retrieve Business](/doc/v1-locations.md#retrieve-business) -* [List Locations](/doc/v1-locations.md#list-locations) - -## Retrieve Business - -Get a business's information. - -```ruby -def retrieve_business -``` - -### Response Type - -[`V1 Merchant Hash`](/doc/models/v1-merchant.md) - -### Example Usage - -```ruby -result = v1_locations_api.retrieve_business() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Locations - -Provides details for a business's locations, including their IDs. - -```ruby -def list_locations -``` - -### Response Type - -[`Array`](/doc/models/v1-merchant.md) - -### Example Usage - -```ruby -result = v1_locations_api.list_locations() - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# V1 Locations + +```ruby +v1_locations_api = client.v1_locations +``` + +## Class Name + +`V1LocationsApi` + +## Methods + +* [Retrieve Business](/doc/v1-locations.md#retrieve-business) +* [List Locations](/doc/v1-locations.md#list-locations) + +## Retrieve Business + +Get a business's information. + +```ruby +def retrieve_business +``` + +### Response Type + +[`V1 Merchant Hash`](/doc/models/v1-merchant.md) + +### Example Usage + +```ruby +result = v1_locations_api.retrieve_business() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Locations + +Provides details for a business's locations, including their IDs. + +```ruby +def list_locations +``` + +### Response Type + +[`Array`](/doc/models/v1-merchant.md) + +### Example Usage + +```ruby +result = v1_locations_api.list_locations() + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/doc/v1-transactions.md b/doc/v1-transactions.md index 2dbb143c..627a952b 100644 --- a/doc/v1-transactions.md +++ b/doc/v1-transactions.md @@ -1,483 +1,483 @@ -# V1 Transactions - -```ruby -v1_transactions_api = client.v1_transactions -``` - -## Class Name - -`V1TransactionsApi` - -## Methods - -* [List Bank Accounts](/doc/v1-transactions.md#list-bank-accounts) -* [Retrieve Bank Account](/doc/v1-transactions.md#retrieve-bank-account) -* [List Orders](/doc/v1-transactions.md#list-orders) -* [Retrieve Order](/doc/v1-transactions.md#retrieve-order) -* [Update Order](/doc/v1-transactions.md#update-order) -* [List Payments](/doc/v1-transactions.md#list-payments) -* [Retrieve Payment](/doc/v1-transactions.md#retrieve-payment) -* [List Refunds](/doc/v1-transactions.md#list-refunds) -* [Create Refund](/doc/v1-transactions.md#create-refund) -* [List Settlements](/doc/v1-transactions.md#list-settlements) -* [Retrieve Settlement](/doc/v1-transactions.md#retrieve-settlement) - -## List Bank Accounts - -Provides non-confidential details for all of a location's associated bank accounts. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API. - -```ruby -def list_bank_accounts(location_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list bank accounts for. | - -### Response Type - -[`Array`](/doc/models/v1-bank-account.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_transactions_api.list_bank_accounts(location_id: location_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Bank Account - -Provides non-confidential details for a merchant's associated bank account. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API. - -```ruby -def retrieve_bank_account(location_id:, - bank_account_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the bank account's associated location. | -| `bank_account_id` | `String` | Template, Required | The bank account's Square-issued ID. You obtain this value from Settlement objects returned. | - -### Response Type - -[`V1 Bank Account Hash`](/doc/models/v1-bank-account.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -bank_account_id = 'bank_account_id0' - -result = v1_transactions_api.retrieve_bank_account(location_id: location_id, bank_account_id: bank_account_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Orders - -Provides summary information for a merchant's online store orders. - -```ruby -def list_orders(location_id:, - order: nil, - limit: nil, - batch_token: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list online store orders for. | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | TThe order in which payments are listed in the response. | -| `limit` | `Integer` | Query, Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | -| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Response Type - -[`Array`](/doc/models/v1-order.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_transactions_api.list_orders(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Order - -Provides comprehensive information for a single online store order, including the order's history. - -```ruby -def retrieve_order(location_id:, - order_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the order's associated location. | -| `order_id` | `String` | Template, Required | The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint | - -### Response Type - -[`V1 Order Hash`](/doc/models/v1-order.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -order_id = 'order_id6' - -result = v1_transactions_api.retrieve_order(location_id: location_id, order_id: order_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Update Order - -Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions: - -```ruby -def update_order(location_id:, - order_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the order's associated location. | -| `order_id` | `String` | Template, Required | The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint | -| `body` | [`V1 Update Order Request Hash`](/doc/models/v1-update-order-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Order Hash`](/doc/models/v1-order.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -order_id = 'order_id6' -body = {} -body[:action] = 'REFUND' - -result = v1_transactions_api.update_order(location_id: location_id, order_id: order_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Payments - -Provides summary information for all payments taken for a given -Square account during a date range. Date ranges cannot exceed 1 year in -length. See Date ranges for details of inclusive and exclusive dates. - -*Note**: Details for payments processed with Square Point of Sale while -in offline mode may not be transmitted to Square for up to 72 hours. -Offline payments have a `created_at` value that reflects the time the -payment was originally processed, not the time it was subsequently -transmitted to Square. Consequently, the ListPayments endpoint might -list an offline payment chronologically between online payments that -were seen in a previous request. - -```ruby -def list_payments(location_id:, - order: nil, - begin_time: nil, - end_time: nil, - limit: nil, - batch_token: nil, - include_partial: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list payments for. If you specify me, this endpoint returns payments aggregated from all of the business's locations. | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which payments are listed in the response. | -| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `Integer` | Query, Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | -| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | -| `include_partial` | `Boolean` | Query, Optional | Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed. | - -### Response Type - -[`Array`](/doc/models/v1-payment.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_transactions_api.list_payments(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Payment - -Provides comprehensive information for a single payment. - -```ruby -def retrieve_payment(location_id:, - payment_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the payment's associated location. | -| `payment_id` | `String` | Template, Required | The Square-issued payment ID. payment_id comes from Payment objects returned by the List Payments endpoint, Settlement objects returned by the List Settlements endpoint, or Refund objects returned by the List Refunds endpoint. | - -### Response Type - -[`V1 Payment Hash`](/doc/models/v1-payment.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -payment_id = 'payment_id0' - -result = v1_transactions_api.retrieve_payment(location_id: location_id, payment_id: payment_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Refunds - -Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length. - -```ruby -def list_refunds(location_id:, - order: nil, - begin_time: nil, - end_time: nil, - limit: nil, - batch_token: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list refunds for. | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | TThe order in which payments are listed in the response. | -| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `Integer` | Query, Optional | The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods. | -| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Response Type - -[`Array`](/doc/models/v1-refund.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_transactions_api.list_refunds(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Create Refund - -Issues a refund for a previously processed payment. You must issue -a refund within 60 days of the associated payment. - -You cannot issue a partial refund for a split tender payment. You must -instead issue a full or partial refund for a particular tender, by -providing the applicable tender id to the V1CreateRefund endpoint. -Issuing a full refund for a split tender payment refunds all tenders -associated with the payment. - -Issuing a refund for a card payment is not reversible. For development -purposes, you can create fake cash payments in Square Point of Sale and -refund them. - -```ruby -def create_refund(location_id:, - body:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the original payment's associated location. | -| `body` | [`V1 Create Refund Request Hash`](/doc/models/v1-create-refund-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -### Response Type - -[`V1 Refund Hash`](/doc/models/v1-refund.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -body = {} -body[:payment_id] = 'payment_id6' -body[:type] = 'FULL' -body[:reason] = 'reason8' - -result = v1_transactions_api.create_refund(location_id: location_id, body: body) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## List Settlements - -Provides summary information for all deposits and withdrawals -initiated by Square to a linked bank account during a date range. Date -ranges cannot exceed one year in length. - -*Note**: the ListSettlements endpoint does not provide entry -information. - -```ruby -def list_settlements(location_id:, - order: nil, - begin_time: nil, - end_time: nil, - limit: nil, - status: nil, - batch_token: nil) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the location to list settlements for. If you specify me, this endpoint returns payments aggregated from all of the business's locations. | -| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | TThe order in which payments are listed in the response. | -| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `Integer` | Query, Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | -| `status` | [`String (V1 List Settlements Request Status)`](/doc/models/v1-list-settlements-request-status.md) | Query, Optional | Provide this parameter to retrieve only settlements with a particular status (SENT or FAILED). | -| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -### Response Type - -[`Array`](/doc/models/v1-settlement.md) - -### Example Usage - -```ruby -location_id = 'location_id4' - -result = v1_transactions_api.list_settlements(location_id: location_id, ) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - -## Retrieve Settlement - -Provides comprehensive information for a single settlement. - -The returned `Settlement` objects include an `entries` field that lists -the transactions that contribute to the settlement total. Most -settlement entries correspond to a payment payout, but settlement -entries are also generated for less common events, like refunds, manual -adjustments, or chargeback holds. - -Square initiates its regular deposits as indicated in the -[Deposit Options with Square](https://squareup.com/help/us/en/article/3807) -help article. Details for a regular deposit are usually not available -from Connect API endpoints before 10 p.m. PST the same day. - -Square does not know when an initiated settlement **completes**, only -whether it has failed. A completed settlement is typically reflected in -a bank account within 3 business days, but in exceptional cases it may -take longer. - -```ruby -def retrieve_settlement(location_id:, - settlement_id:) -``` - -### Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `String` | Template, Required | The ID of the settlements's associated location. | -| `settlement_id` | `String` | Template, Required | The settlement's Square-issued ID. You obtain this value from Settlement objects returned by the List Settlements endpoint. | - -### Response Type - -[`V1 Settlement Hash`](/doc/models/v1-settlement.md) - -### Example Usage - -```ruby -location_id = 'location_id4' -settlement_id = 'settlement_id0' - -result = v1_transactions_api.retrieve_settlement(location_id: location_id, settlement_id: settlement_id) - -if result.success? - puts result.data -elsif result.error? - warn result.errors -end -``` - +# V1 Transactions + +```ruby +v1_transactions_api = client.v1_transactions +``` + +## Class Name + +`V1TransactionsApi` + +## Methods + +* [List Bank Accounts](/doc/v1-transactions.md#list-bank-accounts) +* [Retrieve Bank Account](/doc/v1-transactions.md#retrieve-bank-account) +* [List Orders](/doc/v1-transactions.md#list-orders) +* [Retrieve Order](/doc/v1-transactions.md#retrieve-order) +* [Update Order](/doc/v1-transactions.md#update-order) +* [List Payments](/doc/v1-transactions.md#list-payments) +* [Retrieve Payment](/doc/v1-transactions.md#retrieve-payment) +* [List Refunds](/doc/v1-transactions.md#list-refunds) +* [Create Refund](/doc/v1-transactions.md#create-refund) +* [List Settlements](/doc/v1-transactions.md#list-settlements) +* [Retrieve Settlement](/doc/v1-transactions.md#retrieve-settlement) + +## List Bank Accounts + +Provides non-confidential details for all of a location's associated bank accounts. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API. + +```ruby +def list_bank_accounts(location_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list bank accounts for. | + +### Response Type + +[`Array`](/doc/models/v1-bank-account.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_transactions_api.list_bank_accounts(location_id: location_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Bank Account + +Provides non-confidential details for a merchant's associated bank account. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API. + +```ruby +def retrieve_bank_account(location_id:, + bank_account_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the bank account's associated location. | +| `bank_account_id` | `String` | Template, Required | The bank account's Square-issued ID. You obtain this value from Settlement objects returned. | + +### Response Type + +[`V1 Bank Account Hash`](/doc/models/v1-bank-account.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +bank_account_id = 'bank_account_id0' + +result = v1_transactions_api.retrieve_bank_account(location_id: location_id, bank_account_id: bank_account_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Orders + +Provides summary information for a merchant's online store orders. + +```ruby +def list_orders(location_id:, + order: nil, + limit: nil, + batch_token: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list online store orders for. | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | TThe order in which payments are listed in the response. | +| `limit` | `Integer` | Query, Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | +| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Response Type + +[`Array`](/doc/models/v1-order.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_transactions_api.list_orders(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Order + +Provides comprehensive information for a single online store order, including the order's history. + +```ruby +def retrieve_order(location_id:, + order_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the order's associated location. | +| `order_id` | `String` | Template, Required | The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint | + +### Response Type + +[`V1 Order Hash`](/doc/models/v1-order.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +order_id = 'order_id6' + +result = v1_transactions_api.retrieve_order(location_id: location_id, order_id: order_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Update Order + +Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions: + +```ruby +def update_order(location_id:, + order_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the order's associated location. | +| `order_id` | `String` | Template, Required | The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint | +| `body` | [`V1 Update Order Request Hash`](/doc/models/v1-update-order-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Order Hash`](/doc/models/v1-order.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +order_id = 'order_id6' +body = {} +body[:action] = 'REFUND' + +result = v1_transactions_api.update_order(location_id: location_id, order_id: order_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Payments + +Provides summary information for all payments taken for a given +Square account during a date range. Date ranges cannot exceed 1 year in +length. See Date ranges for details of inclusive and exclusive dates. + +*Note**: Details for payments processed with Square Point of Sale while +in offline mode may not be transmitted to Square for up to 72 hours. +Offline payments have a `created_at` value that reflects the time the +payment was originally processed, not the time it was subsequently +transmitted to Square. Consequently, the ListPayments endpoint might +list an offline payment chronologically between online payments that +were seen in a previous request. + +```ruby +def list_payments(location_id:, + order: nil, + begin_time: nil, + end_time: nil, + limit: nil, + batch_token: nil, + include_partial: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list payments for. If you specify me, this endpoint returns payments aggregated from all of the business's locations. | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which payments are listed in the response. | +| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | +| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | +| `limit` | `Integer` | Query, Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | +| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | +| `include_partial` | `Boolean` | Query, Optional | Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed. | + +### Response Type + +[`Array`](/doc/models/v1-payment.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_transactions_api.list_payments(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Payment + +Provides comprehensive information for a single payment. + +```ruby +def retrieve_payment(location_id:, + payment_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the payment's associated location. | +| `payment_id` | `String` | Template, Required | The Square-issued payment ID. payment_id comes from Payment objects returned by the List Payments endpoint, Settlement objects returned by the List Settlements endpoint, or Refund objects returned by the List Refunds endpoint. | + +### Response Type + +[`V1 Payment Hash`](/doc/models/v1-payment.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +payment_id = 'payment_id0' + +result = v1_transactions_api.retrieve_payment(location_id: location_id, payment_id: payment_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Refunds + +Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length. + +```ruby +def list_refunds(location_id:, + order: nil, + begin_time: nil, + end_time: nil, + limit: nil, + batch_token: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list refunds for. | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | TThe order in which payments are listed in the response. | +| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | +| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | +| `limit` | `Integer` | Query, Optional | The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods. | +| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Response Type + +[`Array`](/doc/models/v1-refund.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_transactions_api.list_refunds(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Create Refund + +Issues a refund for a previously processed payment. You must issue +a refund within 60 days of the associated payment. + +You cannot issue a partial refund for a split tender payment. You must +instead issue a full or partial refund for a particular tender, by +providing the applicable tender id to the V1CreateRefund endpoint. +Issuing a full refund for a split tender payment refunds all tenders +associated with the payment. + +Issuing a refund for a card payment is not reversible. For development +purposes, you can create fake cash payments in Square Point of Sale and +refund them. + +```ruby +def create_refund(location_id:, + body:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the original payment's associated location. | +| `body` | [`V1 Create Refund Request Hash`](/doc/models/v1-create-refund-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +### Response Type + +[`V1 Refund Hash`](/doc/models/v1-refund.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +body = {} +body[:payment_id] = 'payment_id6' +body[:type] = 'FULL' +body[:reason] = 'reason8' + +result = v1_transactions_api.create_refund(location_id: location_id, body: body) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## List Settlements + +Provides summary information for all deposits and withdrawals +initiated by Square to a linked bank account during a date range. Date +ranges cannot exceed one year in length. + +*Note**: the ListSettlements endpoint does not provide entry +information. + +```ruby +def list_settlements(location_id:, + order: nil, + begin_time: nil, + end_time: nil, + limit: nil, + status: nil, + batch_token: nil) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the location to list settlements for. If you specify me, this endpoint returns payments aggregated from all of the business's locations. | +| `order` | [`String (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | TThe order in which payments are listed in the response. | +| `begin_time` | `String` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | +| `end_time` | `String` | Query, Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | +| `limit` | `Integer` | Query, Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | +| `status` | [`String (V1 List Settlements Request Status)`](/doc/models/v1-list-settlements-request-status.md) | Query, Optional | Provide this parameter to retrieve only settlements with a particular status (SENT or FAILED). | +| `batch_token` | `String` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | + +### Response Type + +[`Array`](/doc/models/v1-settlement.md) + +### Example Usage + +```ruby +location_id = 'location_id4' + +result = v1_transactions_api.list_settlements(location_id: location_id, ) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + +## Retrieve Settlement + +Provides comprehensive information for a single settlement. + +The returned `Settlement` objects include an `entries` field that lists +the transactions that contribute to the settlement total. Most +settlement entries correspond to a payment payout, but settlement +entries are also generated for less common events, like refunds, manual +adjustments, or chargeback holds. + +Square initiates its regular deposits as indicated in the +[Deposit Options with Square](https://squareup.com/help/us/en/article/3807) +help article. Details for a regular deposit are usually not available +from Connect API endpoints before 10 p.m. PST the same day. + +Square does not know when an initiated settlement **completes**, only +whether it has failed. A completed settlement is typically reflected in +a bank account within 3 business days, but in exceptional cases it may +take longer. + +```ruby +def retrieve_settlement(location_id:, + settlement_id:) +``` + +### Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `String` | Template, Required | The ID of the settlements's associated location. | +| `settlement_id` | `String` | Template, Required | The settlement's Square-issued ID. You obtain this value from Settlement objects returned by the List Settlements endpoint. | + +### Response Type + +[`V1 Settlement Hash`](/doc/models/v1-settlement.md) + +### Example Usage + +```ruby +location_id = 'location_id4' +settlement_id = 'settlement_id0' + +result = v1_transactions_api.retrieve_settlement(location_id: location_id, settlement_id: settlement_id) + +if result.success? + puts result.data +elsif result.error? + warn result.errors +end +``` + diff --git a/lib/square.rb b/lib/square.rb index ae6d62e5..b7c5f8f7 100644 --- a/lib/square.rb +++ b/lib/square.rb @@ -1,52 +1,53 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -require 'date' -require 'json' -require 'faraday' -require 'certifi' -require 'logging' - -require_relative 'square/api_helper.rb' -require_relative 'square/client.rb' - -# Http -require_relative 'square/http/api_response.rb' -require_relative 'square/http/http_call_back.rb' -require_relative 'square/http/http_client.rb' -require_relative 'square/http/faraday_client.rb' -require_relative 'square/http/http_method_enum.rb' -require_relative 'square/http/http_request.rb' -require_relative 'square/http/http_response.rb' -require_relative 'square/http/auth/o_auth2.rb' - -# Models - -# Exceptions -require_relative 'square/exceptions/api_exception.rb' - -require_relative 'square/configuration.rb' - -# Controllers -require_relative 'square/api/base_api.rb' -require_relative 'square/api/mobile_authorization_api.rb' -require_relative 'square/api/o_auth_api.rb' -require_relative 'square/api/v1_locations_api.rb' -require_relative 'square/api/v1_employees_api.rb' -require_relative 'square/api/v1_transactions_api.rb' -require_relative 'square/api/v1_items_api.rb' -require_relative 'square/api/apple_pay_api.rb' -require_relative 'square/api/catalog_api.rb' -require_relative 'square/api/customers_api.rb' -require_relative 'square/api/employees_api.rb' -require_relative 'square/api/inventory_api.rb' -require_relative 'square/api/labor_api.rb' -require_relative 'square/api/locations_api.rb' -require_relative 'square/api/reporting_api.rb' -require_relative 'square/api/checkout_api.rb' -require_relative 'square/api/orders_api.rb' -require_relative 'square/api/transactions_api.rb' -require_relative 'square/api/payments_api.rb' -require_relative 'square/api/refunds_api.rb' +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +require 'date' +require 'json' +require 'faraday' +require 'certifi' +require 'logging' + +require_relative 'square/api_helper.rb' +require_relative 'square/client.rb' + +# Http +require_relative 'square/http/api_response.rb' +require_relative 'square/http/http_call_back.rb' +require_relative 'square/http/http_client.rb' +require_relative 'square/http/faraday_client.rb' +require_relative 'square/http/http_method_enum.rb' +require_relative 'square/http/http_request.rb' +require_relative 'square/http/http_response.rb' +require_relative 'square/http/auth/o_auth2.rb' + +# Models + +# Exceptions +require_relative 'square/exceptions/api_exception.rb' + +require_relative 'square/configuration.rb' + +# Controllers +require_relative 'square/api/base_api.rb' +require_relative 'square/api/mobile_authorization_api.rb' +require_relative 'square/api/o_auth_api.rb' +require_relative 'square/api/v1_locations_api.rb' +require_relative 'square/api/v1_employees_api.rb' +require_relative 'square/api/v1_transactions_api.rb' +require_relative 'square/api/v1_items_api.rb' +require_relative 'square/api/apple_pay_api.rb' +require_relative 'square/api/catalog_api.rb' +require_relative 'square/api/customers_api.rb' +require_relative 'square/api/employees_api.rb' +require_relative 'square/api/inventory_api.rb' +require_relative 'square/api/labor_api.rb' +require_relative 'square/api/locations_api.rb' +require_relative 'square/api/reporting_api.rb' +require_relative 'square/api/checkout_api.rb' +require_relative 'square/api/orders_api.rb' +require_relative 'square/api/transactions_api.rb' +require_relative 'square/api/merchants_api.rb' +require_relative 'square/api/payments_api.rb' +require_relative 'square/api/refunds_api.rb' diff --git a/lib/square/api/apple_pay_api.rb b/lib/square/api/apple_pay_api.rb index fa36abfd..9800001e 100644 --- a/lib/square/api/apple_pay_api.rb +++ b/lib/square/api/apple_pay_api.rb @@ -1,55 +1,55 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # ApplePayApi - class ApplePayApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Activates a domain for use with Web Apple Pay and Square. A validation - # will be performed on this domain by Apple to ensure is it properly set up - # as - # an Apple Pay enabled domain. - # This endpoint provides an easy way for platform developers to bulk - # activate - # Web Apple Pay with Square for merchants using their platform. - # To learn more about Apple Pay on Web see the Apple Pay section in the - # [Embedding the Square Payment - # Form](https://developer.squareup.com/docs/payment-form/add-digital-wallets - # /apple-pay) guide. - # @param [RegisterDomainRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [RegisterDomainResponse Hash] response from the API call - def register_domain(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/apple-pay/domains' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # ApplePayApi + class ApplePayApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Activates a domain for use with Web Apple Pay and Square. A validation + # will be performed on this domain by Apple to ensure is it properly set up + # as + # an Apple Pay enabled domain. + # This endpoint provides an easy way for platform developers to bulk + # activate + # Web Apple Pay with Square for merchants using their platform. + # To learn more about Apple Pay on Web see the Apple Pay section in the + # [Embedding the Square Payment + # Form](https://developer.squareup.com/docs/payment-form/add-digital-wallets + # /apple-pay) guide. + # @param [RegisterDomainRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [RegisterDomainResponse Hash] response from the API call + def register_domain(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/apple-pay/domains' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/base_api.rb b/lib/square/api/base_api.rb index 7310b4ee..88f64c96 100644 --- a/lib/square/api/base_api.rb +++ b/lib/square/api/base_api.rb @@ -1,45 +1,48 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # BaseApi. - class BaseApi - attr_accessor :config, :http_call_back - - def initialize(config, http_call_back: nil) - @config = config - @http_call_back = http_call_back - - @global_headers = { - 'user-agent' => 'Square-Connect-Ruby-3.20190814.0', - 'Square-Version' => '2019-08-14' - } - end - - def validate_parameters(args) - args.each do |_name, value| - if value.nil? - raise ArgumentError, "Required parameter #{_name} cannot be nil." - end - end - end - - def execute_request(request, binary: false) - @http_call_back.on_before_request(request) if @http_call_back - - APIHelper.clean_hash(request.headers) - request.headers = @global_headers.clone.merge(request.headers) - - response = if binary - config.http_client.execute_as_binary(request) - else - config.http_client.execute_as_string(request) - end - @http_call_back.on_after_response(response) if @http_call_back - - response - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # BaseApi. + class BaseApi + attr_accessor :config, :http_call_back + + def initialize(config, http_call_back: nil) + @config = config + @http_call_back = http_call_back + + @global_headers = { + 'user-agent' => 'Square-Ruby-SDK/3.20190925.0', + 'Square-Version' => '2019-09-25' + } + end + + def validate_parameters(args) + args.each do |_name, value| + if value.nil? + raise ArgumentError, "Required parameter #{_name} cannot be nil." + end + end + end + + def execute_request(request, binary: false) + @http_call_back.on_before_request(request) if @http_call_back + + APIHelper.clean_hash(request.headers) + request.headers.merge!(@global_headers) + unless config.additional_headers.nil? + request.headers.merge!(config.additional_headers) + end + + response = if binary + config.http_client.execute_as_binary(request) + else + config.http_client.execute_as_string(request) + end + @http_call_back.on_after_response(response) if @http_call_back + + response + end + end +end diff --git a/lib/square/api/catalog_api.rb b/lib/square/api/catalog_api.rb index 2b4db34b..46c7e957 100644 --- a/lib/square/api/catalog_api.rb +++ b/lib/square/api/catalog_api.rb @@ -1,461 +1,461 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # CatalogApi - class CatalogApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Deletes a set of [CatalogItem](#type-catalogitem)s based on the - # provided list of target IDs and returns a set of successfully deleted IDs - # in - # the response. Deletion is a cascading event such that all children of the - # targeted object are also deleted. For example, deleting a CatalogItem will - # also delete all of its [CatalogItemVariation](#type-catalogitemvariation) - # children. - # `BatchDeleteCatalogObjects` succeeds even if only a portion of the - # targeted - # IDs can be deleted. The response will only include IDs that were - # actually deleted. - # @param [BatchDeleteCatalogObjectsRequest] body Required parameter: An - # object containing the fields to POST for the request. See the - # corresponding object definition for field details. - # @return [BatchDeleteCatalogObjectsResponse Hash] response from the API call - def batch_delete_catalog_objects(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/batch-delete' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a set of objects based on the provided ID. - # Each [CatalogItem](#type-catalogitem) returned in the set includes all of - # its - # child information including: all of its - # [CatalogItemVariation](#type-catalogitemvariation) objects, references to - # its [CatalogModifierList](#type-catalogmodifierlist) objects, and the ids - # of - # any [CatalogTax](#type-catalogtax) objects that apply to it. - # @param [BatchRetrieveCatalogObjectsRequest] body Required parameter: An - # object containing the fields to POST for the request. See the - # corresponding object definition for field details. - # @return [BatchRetrieveCatalogObjectsResponse Hash] response from the API call - def batch_retrieve_catalog_objects(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/batch-retrieve' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates or updates up to 10,000 target objects based on the provided - # list of objects. The target objects are grouped into batches and each - # batch is - # inserted/updated in an all-or-nothing manner. If an object within a batch - # is - # malformed in some way, or violates a database constraint, the entire batch - # containing that item will be disregarded. However, other batches in the - # same - # request may still succeed. Each batch may contain up to 1,000 objects, and - # batches will be processed in order as long as the total object count for - # the - # request (items, variations, modifier lists, discounts, and taxes) is no - # more - # than 10,000. - # @param [BatchUpsertCatalogObjectsRequest] body Required parameter: An - # object containing the fields to POST for the request. See the - # corresponding object definition for field details. - # @return [BatchUpsertCatalogObjectsResponse Hash] response from the API call - def batch_upsert_catalog_objects(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/batch-upsert' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns information about the Square Catalog API, such as batch size - # limits for `BatchUpsertCatalogObjects`. - # @return [CatalogInfoResponse Hash] response from the API call - def catalog_info - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/info' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a list of [CatalogObject](#type-catalogobject)s that includes - # all objects of a set of desired types (for example, all - # [CatalogItem](#type-catalogitem) - # and [CatalogTax](#type-catalogtax) objects) in the catalog. The `types` - # parameter - # is specified as a comma-separated list of valid - # [CatalogObject](#type-catalogobject) types: - # `ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, - # `DISCOUNT`, `TAX`. - # __Important:__ ListCatalog does not return deleted catalog items. To - # retrieve - # deleted catalog items, use SearchCatalogObjects and set - # `include_deleted_objects` - # to `true`. - # @param [String] cursor Optional parameter: The pagination cursor returned - # in the previous response. Leave unset for an initial request. See - # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) - # for more information. - # @param [String] types Optional parameter: An optional case-insensitive, - # comma-separated list of object types to retrieve, for example - # `ITEM,ITEM_VARIATION,CATEGORY,IMAGE`. The legal values are taken from the - # [CatalogObjectType](#type-catalogobjecttype) enumeration, namely `ITEM`, - # `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, `MODIFIER`, - # `MODIFIER_LIST`, or `IMAGE`. - # @return [ListCatalogResponse Hash] response from the API call - def list_catalog(cursor: nil, - types: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/list' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'cursor' => cursor, - 'types' => types - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates or updates the target [CatalogObject](#type-catalogobject). - # @param [UpsertCatalogObjectRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [UpsertCatalogObjectResponse Hash] response from the API call - def upsert_catalog_object(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/object' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes a single [CatalogObject](#type-catalogobject) based on the - # provided ID and returns the set of successfully deleted IDs in the - # response. - # Deletion is a cascading event such that all children of the targeted - # object - # are also deleted. For example, deleting a [CatalogItem](#type-catalogitem) - # will also delete all of its - # [CatalogItemVariation](#type-catalogitemvariation) children. - # @param [String] object_id Required parameter: The ID of the - # [CatalogObject](#type-catalogobject) to be deleted. When an object is - # deleted, other objects in the graph that depend on that object will be - # deleted as well (for example, deleting a [CatalogItem](#type-catalogitem) - # will delete its [CatalogItemVariation](#type-catalogitemvariation)s). - # @return [DeleteCatalogObjectResponse Hash] response from the API call - def delete_catalog_object(object_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/object/{object_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'object_id' => object_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a single [CatalogItem](#type-catalogitem) as a - # [CatalogObject](#type-catalogobject) based on the provided ID. The - # returned - # object includes all of the relevant [CatalogItem](#type-catalogitem) - # information including: [CatalogItemVariation](#type-catalogitemvariation) - # children, references to its - # [CatalogModifierList](#type-catalogmodifierlist) objects, and the ids of - # any [CatalogTax](#type-catalogtax) objects that apply to it. - # @param [String] object_id Required parameter: The object ID of any type of - # [CatalogObject](#type-catalogobject)s to be retrieved. - # @param [Boolean] include_related_objects Optional parameter: If `true`, - # the response will include additional objects that are related to the - # requested object, as follows: If the `object` field of the response - # contains a [CatalogItem](#type-catalogitem), its associated - # [CatalogCategory](#type-catalogcategory), - # [CatalogTax](#type-catalogtax)es, [CatalogImage](#type-catalogimage)s and - # [CatalogModifierList](#type-catalogmodifierlist)s will be returned in the - # `related_objects` field of the response. If the `object` field of the - # response contains a [CatalogItemVariation](#type-catalogitemvariation), - # its parent [CatalogItem](#type-catalogitem) will be returned in the - # `related_objects` field of the response. Default value: `false` - # @return [RetrieveCatalogObjectResponse Hash] response from the API call - def retrieve_catalog_object(object_id:, - include_related_objects: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/object/{object_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'object_id' => object_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'include_related_objects' => include_related_objects - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Queries the targeted catalog using a variety of query types: - # [CatalogQuerySortedAttribute](#type-catalogquerysortedattribute), - # [CatalogQueryExact](#type-catalogqueryexact), - # [CatalogQueryRange](#type-catalogqueryrange), - # [CatalogQueryText](#type-catalogquerytext), - # [CatalogQueryItemsForTax](#type-catalogqueryitemsfortax), and - # [CatalogQueryItemsForModifierList](#type-catalogqueryitemsformodifierlist) - # . - # @param [SearchCatalogObjectsRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [SearchCatalogObjectsResponse Hash] response from the API call - def search_catalog_objects(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/search' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Updates the [CatalogModifierList](#type-catalogmodifierlist) objects - # that apply to the targeted [CatalogItem](#type-catalogitem) without having - # to perform an upsert on the entire item. - # @param [UpdateItemModifierListsRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [UpdateItemModifierListsResponse Hash] response from the API call - def update_item_modifier_lists(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/update-item-modifier-lists' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Updates the [CatalogTax](#type-catalogtax) objects that apply to the - # targeted [CatalogItem](#type-catalogitem) without having to perform an - # upsert on the entire item. - # @param [UpdateItemTaxesRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [UpdateItemTaxesResponse Hash] response from the API call - def update_item_taxes(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/catalog/update-item-taxes' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # CatalogApi + class CatalogApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Deletes a set of [CatalogItem](#type-catalogitem)s based on the + # provided list of target IDs and returns a set of successfully deleted IDs + # in + # the response. Deletion is a cascading event such that all children of the + # targeted object are also deleted. For example, deleting a CatalogItem will + # also delete all of its [CatalogItemVariation](#type-catalogitemvariation) + # children. + # `BatchDeleteCatalogObjects` succeeds even if only a portion of the + # targeted + # IDs can be deleted. The response will only include IDs that were + # actually deleted. + # @param [BatchDeleteCatalogObjectsRequest] body Required parameter: An + # object containing the fields to POST for the request. See the + # corresponding object definition for field details. + # @return [BatchDeleteCatalogObjectsResponse Hash] response from the API call + def batch_delete_catalog_objects(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/batch-delete' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a set of objects based on the provided ID. + # Each [CatalogItem](#type-catalogitem) returned in the set includes all of + # its + # child information including: all of its + # [CatalogItemVariation](#type-catalogitemvariation) objects, references to + # its [CatalogModifierList](#type-catalogmodifierlist) objects, and the ids + # of + # any [CatalogTax](#type-catalogtax) objects that apply to it. + # @param [BatchRetrieveCatalogObjectsRequest] body Required parameter: An + # object containing the fields to POST for the request. See the + # corresponding object definition for field details. + # @return [BatchRetrieveCatalogObjectsResponse Hash] response from the API call + def batch_retrieve_catalog_objects(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/batch-retrieve' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates or updates up to 10,000 target objects based on the provided + # list of objects. The target objects are grouped into batches and each + # batch is + # inserted/updated in an all-or-nothing manner. If an object within a batch + # is + # malformed in some way, or violates a database constraint, the entire batch + # containing that item will be disregarded. However, other batches in the + # same + # request may still succeed. Each batch may contain up to 1,000 objects, and + # batches will be processed in order as long as the total object count for + # the + # request (items, variations, modifier lists, discounts, and taxes) is no + # more + # than 10,000. + # @param [BatchUpsertCatalogObjectsRequest] body Required parameter: An + # object containing the fields to POST for the request. See the + # corresponding object definition for field details. + # @return [BatchUpsertCatalogObjectsResponse Hash] response from the API call + def batch_upsert_catalog_objects(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/batch-upsert' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns information about the Square Catalog API, such as batch size + # limits for `BatchUpsertCatalogObjects`. + # @return [CatalogInfoResponse Hash] response from the API call + def catalog_info + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/info' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a list of [CatalogObject](#type-catalogobject)s that includes + # all objects of a set of desired types (for example, all + # [CatalogItem](#type-catalogitem) + # and [CatalogTax](#type-catalogtax) objects) in the catalog. The `types` + # parameter + # is specified as a comma-separated list of valid + # [CatalogObject](#type-catalogobject) types: + # `ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, + # `DISCOUNT`, `TAX`. + # __Important:__ ListCatalog does not return deleted catalog items. To + # retrieve + # deleted catalog items, use SearchCatalogObjects and set + # `include_deleted_objects` + # to `true`. + # @param [String] cursor Optional parameter: The pagination cursor returned + # in the previous response. Leave unset for an initial request. See + # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) + # for more information. + # @param [String] types Optional parameter: An optional case-insensitive, + # comma-separated list of object types to retrieve, for example + # `ITEM,ITEM_VARIATION,CATEGORY,IMAGE`. The legal values are taken from the + # [CatalogObjectType](#type-catalogobjecttype) enumeration, namely `ITEM`, + # `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, `MODIFIER`, + # `MODIFIER_LIST`, or `IMAGE`. + # @return [ListCatalogResponse Hash] response from the API call + def list_catalog(cursor: nil, + types: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/list' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'cursor' => cursor, + 'types' => types + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates or updates the target [CatalogObject](#type-catalogobject). + # @param [UpsertCatalogObjectRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [UpsertCatalogObjectResponse Hash] response from the API call + def upsert_catalog_object(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/object' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes a single [CatalogObject](#type-catalogobject) based on the + # provided ID and returns the set of successfully deleted IDs in the + # response. + # Deletion is a cascading event such that all children of the targeted + # object + # are also deleted. For example, deleting a [CatalogItem](#type-catalogitem) + # will also delete all of its + # [CatalogItemVariation](#type-catalogitemvariation) children. + # @param [String] object_id Required parameter: The ID of the + # [CatalogObject](#type-catalogobject) to be deleted. When an object is + # deleted, other objects in the graph that depend on that object will be + # deleted as well (for example, deleting a [CatalogItem](#type-catalogitem) + # will delete its [CatalogItemVariation](#type-catalogitemvariation)s). + # @return [DeleteCatalogObjectResponse Hash] response from the API call + def delete_catalog_object(object_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/object/{object_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'object_id' => object_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a single [CatalogItem](#type-catalogitem) as a + # [CatalogObject](#type-catalogobject) based on the provided ID. The + # returned + # object includes all of the relevant [CatalogItem](#type-catalogitem) + # information including: [CatalogItemVariation](#type-catalogitemvariation) + # children, references to its + # [CatalogModifierList](#type-catalogmodifierlist) objects, and the ids of + # any [CatalogTax](#type-catalogtax) objects that apply to it. + # @param [String] object_id Required parameter: The object ID of any type of + # [CatalogObject](#type-catalogobject)s to be retrieved. + # @param [Boolean] include_related_objects Optional parameter: If `true`, + # the response will include additional objects that are related to the + # requested object, as follows: If the `object` field of the response + # contains a [CatalogItem](#type-catalogitem), its associated + # [CatalogCategory](#type-catalogcategory), + # [CatalogTax](#type-catalogtax)es, [CatalogImage](#type-catalogimage)s and + # [CatalogModifierList](#type-catalogmodifierlist)s will be returned in the + # `related_objects` field of the response. If the `object` field of the + # response contains a [CatalogItemVariation](#type-catalogitemvariation), + # its parent [CatalogItem](#type-catalogitem) will be returned in the + # `related_objects` field of the response. Default value: `false` + # @return [RetrieveCatalogObjectResponse Hash] response from the API call + def retrieve_catalog_object(object_id:, + include_related_objects: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/object/{object_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'object_id' => object_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'include_related_objects' => include_related_objects + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Queries the targeted catalog using a variety of query types: + # [CatalogQuerySortedAttribute](#type-catalogquerysortedattribute), + # [CatalogQueryExact](#type-catalogqueryexact), + # [CatalogQueryRange](#type-catalogqueryrange), + # [CatalogQueryText](#type-catalogquerytext), + # [CatalogQueryItemsForTax](#type-catalogqueryitemsfortax), and + # [CatalogQueryItemsForModifierList](#type-catalogqueryitemsformodifierlist) + # . + # @param [SearchCatalogObjectsRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [SearchCatalogObjectsResponse Hash] response from the API call + def search_catalog_objects(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/search' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Updates the [CatalogModifierList](#type-catalogmodifierlist) objects + # that apply to the targeted [CatalogItem](#type-catalogitem) without having + # to perform an upsert on the entire item. + # @param [UpdateItemModifierListsRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [UpdateItemModifierListsResponse Hash] response from the API call + def update_item_modifier_lists(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/update-item-modifier-lists' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Updates the [CatalogTax](#type-catalogtax) objects that apply to the + # targeted [CatalogItem](#type-catalogitem) without having to perform an + # upsert on the entire item. + # @param [UpdateItemTaxesRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [UpdateItemTaxesResponse Hash] response from the API call + def update_item_taxes(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/catalog/update-item-taxes' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/checkout_api.rb b/lib/square/api/checkout_api.rb index 88faf6cb..d446a105 100644 --- a/lib/square/api/checkout_api.rb +++ b/lib/square/api/checkout_api.rb @@ -1,54 +1,54 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # CheckoutApi - class CheckoutApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Links a `checkoutId` to a `checkout_page_url` that customers will - # be directed to in order to provide their payment information using a - # payment processing workflow hosted on connect.squareup.com. - # @param [String] location_id Required parameter: The ID of the business - # location to associate the checkout with. - # @param [CreateCheckoutRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [CreateCheckoutResponse Hash] response from the API call - def create_checkout(location_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/checkouts' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # CheckoutApi + class CheckoutApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Links a `checkoutId` to a `checkout_page_url` that customers will + # be directed to in order to provide their payment information using a + # payment processing workflow hosted on connect.squareup.com. + # @param [String] location_id Required parameter: The ID of the business + # location to associate the checkout with. + # @param [CreateCheckoutRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [CreateCheckoutResponse Hash] response from the API call + def create_checkout(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/checkouts' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/customers_api.rb b/lib/square/api/customers_api.rb index 91924a8f..ffbd9f84 100644 --- a/lib/square/api/customers_api.rb +++ b/lib/square/api/customers_api.rb @@ -1,335 +1,335 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # CustomersApi - class CustomersApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Lists a business's customers. - # @param [String] cursor Optional parameter: A pagination cursor returned by - # a previous call to this endpoint. Provide this to retrieve the next set of - # results for your original query. See - # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) - # for more information. - # @param [CustomerSortField] sort_field Optional parameter: Indicates how - # Customers should be sorted. Default: `DEFAULT`. - # @param [SortOrder] sort_order Optional parameter: Indicates whether - # Customers should be sorted in ascending (`ASC`) or descending (`DESC`) - # order. Default: `ASC`. - # @return [ListCustomersResponse Hash] response from the API call - def list_customers(cursor: nil, - sort_field: nil, - sort_order: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/customers' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'cursor' => cursor, - 'sort_field' => sort_field, - 'sort_order' => sort_order - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates a new customer for a business, which can have associated cards on - # file. - # You must provide __at least one__ of the following values in your request - # to this - # endpoint: - # - `given_name` - # - `family_name` - # - `company_name` - # - `email_address` - # - `phone_number` - # @param [CreateCustomerRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [CreateCustomerResponse Hash] response from the API call - def create_customer(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/customers' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Searches the customer profiles associated with a Square account. - # Calling SearchCustomers without an explicit query parameter returns all - # customer profiles ordered alphabetically based on `given_name` and - # `family_name`. - # @param [SearchCustomersRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [SearchCustomersResponse Hash] response from the API call - def search_customers(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/customers/search' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes a customer from a business, along with any linked cards on file. - # When two profiles - # are merged into a single profile, that profile is assigned a new - # `customer_id`. You must use the - # new `customer_id` to delete merged profiles. - # @param [String] customer_id Required parameter: The ID of the customer to - # delete. - # @return [DeleteCustomerResponse Hash] response from the API call - def delete_customer(customer_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/customers/{customer_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'customer_id' => customer_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns details for a single customer. - # @param [String] customer_id Required parameter: The ID of the customer to - # retrieve. - # @return [RetrieveCustomerResponse Hash] response from the API call - def retrieve_customer(customer_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/customers/{customer_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'customer_id' => customer_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Updates the details of an existing customer. When two profiles are merged - # into a single profile, that profile is assigned a new `customer_id`. You - # must use - # the new `customer_id` to update merged profiles. - # You cannot edit a customer's cards on file with this endpoint. To make - # changes - # to a card on file, you must delete the existing card on file with the - # [DeleteCustomerCard](#endpoint-customers-deletecustomercard) endpoint, - # then - # create a new one with the - # [CreateCustomerCard](#endpoint-customers-createcustomercard) endpoint. - # @param [String] customer_id Required parameter: The ID of the customer to - # update. - # @param [UpdateCustomerRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [UpdateCustomerResponse Hash] response from the API call - def update_customer(customer_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/customers/{customer_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'customer_id' => customer_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Adds a card on file to an existing customer. - # As with charges, calls to `CreateCustomerCard` are idempotent. Multiple - # calls with the same card nonce return the same card record that was - # created - # with the provided nonce during the _first_ call. - # Cards on file are automatically updated on a monthly basis to confirm they - # are still valid and can be charged. - # @param [String] customer_id Required parameter: The Square ID of the - # customer profile the card is linked to. - # @param [CreateCustomerCardRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [CreateCustomerCardResponse Hash] response from the API call - def create_customer_card(customer_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/customers/{customer_id}/cards' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'customer_id' => customer_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Removes a card on file from a customer. - # @param [String] customer_id Required parameter: The ID of the customer - # that the card on file belongs to. - # @param [String] card_id Required parameter: The ID of the card on file to - # delete. - # @return [DeleteCustomerCardResponse Hash] response from the API call - def delete_customer_card(customer_id:, - card_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/customers/{customer_id}/cards/{card_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'customer_id' => customer_id, - 'card_id' => card_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # CustomersApi + class CustomersApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Lists a business's customers. + # @param [String] cursor Optional parameter: A pagination cursor returned by + # a previous call to this endpoint. Provide this to retrieve the next set of + # results for your original query. See + # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) + # for more information. + # @param [CustomerSortField] sort_field Optional parameter: Indicates how + # Customers should be sorted. Default: `DEFAULT`. + # @param [SortOrder] sort_order Optional parameter: Indicates whether + # Customers should be sorted in ascending (`ASC`) or descending (`DESC`) + # order. Default: `ASC`. + # @return [ListCustomersResponse Hash] response from the API call + def list_customers(cursor: nil, + sort_field: nil, + sort_order: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/customers' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'cursor' => cursor, + 'sort_field' => sort_field, + 'sort_order' => sort_order + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates a new customer for a business, which can have associated cards on + # file. + # You must provide __at least one__ of the following values in your request + # to this + # endpoint: + # - `given_name` + # - `family_name` + # - `company_name` + # - `email_address` + # - `phone_number` + # @param [CreateCustomerRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [CreateCustomerResponse Hash] response from the API call + def create_customer(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/customers' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Searches the customer profiles associated with a Square account. + # Calling SearchCustomers without an explicit query parameter returns all + # customer profiles ordered alphabetically based on `given_name` and + # `family_name`. + # @param [SearchCustomersRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [SearchCustomersResponse Hash] response from the API call + def search_customers(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/customers/search' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes a customer from a business, along with any linked cards on file. + # When two profiles + # are merged into a single profile, that profile is assigned a new + # `customer_id`. You must use the + # new `customer_id` to delete merged profiles. + # @param [String] customer_id Required parameter: The ID of the customer to + # delete. + # @return [DeleteCustomerResponse Hash] response from the API call + def delete_customer(customer_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/customers/{customer_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'customer_id' => customer_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns details for a single customer. + # @param [String] customer_id Required parameter: The ID of the customer to + # retrieve. + # @return [RetrieveCustomerResponse Hash] response from the API call + def retrieve_customer(customer_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/customers/{customer_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'customer_id' => customer_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Updates the details of an existing customer. When two profiles are merged + # into a single profile, that profile is assigned a new `customer_id`. You + # must use + # the new `customer_id` to update merged profiles. + # You cannot edit a customer's cards on file with this endpoint. To make + # changes + # to a card on file, you must delete the existing card on file with the + # [DeleteCustomerCard](#endpoint-customers-deletecustomercard) endpoint, + # then + # create a new one with the + # [CreateCustomerCard](#endpoint-customers-createcustomercard) endpoint. + # @param [String] customer_id Required parameter: The ID of the customer to + # update. + # @param [UpdateCustomerRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [UpdateCustomerResponse Hash] response from the API call + def update_customer(customer_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/customers/{customer_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'customer_id' => customer_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Adds a card on file to an existing customer. + # As with charges, calls to `CreateCustomerCard` are idempotent. Multiple + # calls with the same card nonce return the same card record that was + # created + # with the provided nonce during the _first_ call. + # Cards on file are automatically updated on a monthly basis to confirm they + # are still valid and can be charged. + # @param [String] customer_id Required parameter: The Square ID of the + # customer profile the card is linked to. + # @param [CreateCustomerCardRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [CreateCustomerCardResponse Hash] response from the API call + def create_customer_card(customer_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/customers/{customer_id}/cards' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'customer_id' => customer_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Removes a card on file from a customer. + # @param [String] customer_id Required parameter: The ID of the customer + # that the card on file belongs to. + # @param [String] card_id Required parameter: The ID of the card on file to + # delete. + # @return [DeleteCustomerCardResponse Hash] response from the API call + def delete_customer_card(customer_id:, + card_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/customers/{customer_id}/cards/{card_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'customer_id' => customer_id, + 'card_id' => card_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/employees_api.rb b/lib/square/api/employees_api.rb index 3eb7646d..4f9a75b7 100644 --- a/lib/square/api/employees_api.rb +++ b/lib/square/api/employees_api.rb @@ -1,91 +1,91 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # EmployeesApi - class EmployeesApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Gets a list of `Employee` objects for a business. - # @param [String] location_id Optional parameter: Filter employees returned - # to only those that are associated with the specified location. - # @param [EmployeeStatus] status Optional parameter: Specifies the - # EmployeeStatus to filter the employee by. - # @param [Integer] limit Optional parameter: The number of employees to be - # returned on each page. - # @param [String] cursor Optional parameter: The token required to retrieve - # the specified page of results. - # @return [ListEmployeesResponse Hash] response from the API call - def list_employees(location_id: nil, - status: nil, - limit: nil, - cursor: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/employees' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'location_id' => location_id, - 'status' => status, - 'limit' => limit, - 'cursor' => cursor - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Gets an `Employee` by Square-assigned employee `ID` (UUID) - # @param [String] id Required parameter: UUID for the employee that was - # requested. - # @return [RetrieveEmployeeResponse Hash] response from the API call - def retrieve_employee(id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/employees/{id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'id' => id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # EmployeesApi + class EmployeesApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Gets a list of `Employee` objects for a business. + # @param [String] location_id Optional parameter: Filter employees returned + # to only those that are associated with the specified location. + # @param [EmployeeStatus] status Optional parameter: Specifies the + # EmployeeStatus to filter the employee by. + # @param [Integer] limit Optional parameter: The number of employees to be + # returned on each page. + # @param [String] cursor Optional parameter: The token required to retrieve + # the specified page of results. + # @return [ListEmployeesResponse Hash] response from the API call + def list_employees(location_id: nil, + status: nil, + limit: nil, + cursor: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/employees' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'location_id' => location_id, + 'status' => status, + 'limit' => limit, + 'cursor' => cursor + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Gets an `Employee` by Square-assigned employee `ID` (UUID) + # @param [String] id Required parameter: UUID for the employee that was + # requested. + # @return [RetrieveEmployeeResponse Hash] response from the API call + def retrieve_employee(id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/employees/{id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'id' => id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/inventory_api.rb b/lib/square/api/inventory_api.rb index af613cf5..d801090e 100644 --- a/lib/square/api/inventory_api.rb +++ b/lib/square/api/inventory_api.rb @@ -1,300 +1,300 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # InventoryApi - class InventoryApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Returns the [InventoryAdjustment](#type-inventoryadjustment) object - # with the provided `adjustment_id`. - # @param [String] adjustment_id Required parameter: ID of the - # [InventoryAdjustment](#type-inventoryadjustment) to retrieve. - # @return [RetrieveInventoryAdjustmentResponse Hash] response from the API call - def retrieve_inventory_adjustment(adjustment_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/inventory/adjustment/{adjustment_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'adjustment_id' => adjustment_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Applies adjustments and counts to the provided item quantities. - # On success: returns the current calculated counts for all objects - # referenced in the request. - # On failure: returns a list of related errors. - # @param [BatchChangeInventoryRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [BatchChangeInventoryResponse Hash] response from the API call - def batch_change_inventory(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/inventory/batch-change' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns historical physical counts and adjustments based on the - # provided filter criteria. - # Results are paginated and sorted in ascending order according their - # `occurred_at` timestamp (oldest first). - # BatchRetrieveInventoryChanges is a catch-all query endpoint for queries - # that cannot be handled by other, simpler endpoints. - # @param [BatchRetrieveInventoryChangesRequest] body Required parameter: An - # object containing the fields to POST for the request. See the - # corresponding object definition for field details. - # @return [BatchRetrieveInventoryChangesResponse Hash] response from the API call - def batch_retrieve_inventory_changes(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/inventory/batch-retrieve-changes' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns current counts for the provided - # [CatalogObject](#type-catalogobject)s at the requested - # [Location](#type-location)s. - # Results are paginated and sorted in descending order according to their - # `calculated_at` timestamp (newest first). - # When `updated_after` is specified, only counts that have changed since - # that - # time (based on the server timestamp for the most recent change) are - # returned. This allows clients to perform a "sync" operation, for example - # in response to receiving a Webhook notification. - # @param [BatchRetrieveInventoryCountsRequest] body Required parameter: An - # object containing the fields to POST for the request. See the - # corresponding object definition for field details. - # @return [BatchRetrieveInventoryCountsResponse Hash] response from the API call - def batch_retrieve_inventory_counts(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/inventory/batch-retrieve-counts' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns the [InventoryPhysicalCount](#type-inventoryphysicalcount) - # object with the provided `physical_count_id`. - # @param [String] physical_count_id Required parameter: ID of the - # [InventoryPhysicalCount](#type-inventoryphysicalcount) to retrieve. - # @return [RetrieveInventoryPhysicalCountResponse Hash] response from the API call - def retrieve_inventory_physical_count(physical_count_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/inventory/physical-count/{physical_count_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'physical_count_id' => physical_count_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Retrieves the current calculated stock count for a given - # [CatalogObject](#type-catalogobject) at a given set of - # [Location](#type-location)s. Responses are paginated and unsorted. - # For more sophisticated queries, use a batch endpoint. - # @param [String] catalog_object_id Required parameter: ID of the - # [CatalogObject](#type-catalogobject) to retrieve. - # @param [String] location_ids Optional parameter: The - # [Location](#type-location) IDs to look up as a comma-separated list. An - # empty list queries all locations. - # @param [String] cursor Optional parameter: A pagination cursor returned by - # a previous call to this endpoint. Provide this to retrieve the next set of - # results for the original query. See - # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) - # for more information. - # @return [RetrieveInventoryCountResponse Hash] response from the API call - def retrieve_inventory_count(catalog_object_id:, - location_ids: nil, - cursor: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/inventory/{catalog_object_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'catalog_object_id' => catalog_object_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'location_ids' => location_ids, - 'cursor' => cursor - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a set of physical counts and inventory adjustments for the - # provided [CatalogObject](#type-catalogobject) at the requested - # [Location](#type-location)s. - # Results are paginated and sorted in descending order according to their - # `occurred_at` timestamp (newest first). - # There are no limits on how far back the caller can page. This endpoint is - # useful when displaying recent changes for a specific item. For more - # sophisticated queries, use a batch endpoint. - # @param [String] catalog_object_id Required parameter: ID of the - # [CatalogObject](#type-catalogobject) to retrieve. - # @param [String] location_ids Optional parameter: The - # [Location](#type-location) IDs to look up as a comma-separated list. An - # empty list queries all locations. - # @param [String] cursor Optional parameter: A pagination cursor returned by - # a previous call to this endpoint. Provide this to retrieve the next set of - # results for the original query. See - # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) - # for more information. - # @return [RetrieveInventoryChangesResponse Hash] response from the API call - def retrieve_inventory_changes(catalog_object_id:, - location_ids: nil, - cursor: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/inventory/{catalog_object_id}/changes' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'catalog_object_id' => catalog_object_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'location_ids' => location_ids, - 'cursor' => cursor - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # InventoryApi + class InventoryApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Returns the [InventoryAdjustment](#type-inventoryadjustment) object + # with the provided `adjustment_id`. + # @param [String] adjustment_id Required parameter: ID of the + # [InventoryAdjustment](#type-inventoryadjustment) to retrieve. + # @return [RetrieveInventoryAdjustmentResponse Hash] response from the API call + def retrieve_inventory_adjustment(adjustment_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/inventory/adjustment/{adjustment_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'adjustment_id' => adjustment_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Applies adjustments and counts to the provided item quantities. + # On success: returns the current calculated counts for all objects + # referenced in the request. + # On failure: returns a list of related errors. + # @param [BatchChangeInventoryRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [BatchChangeInventoryResponse Hash] response from the API call + def batch_change_inventory(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/inventory/batch-change' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns historical physical counts and adjustments based on the + # provided filter criteria. + # Results are paginated and sorted in ascending order according their + # `occurred_at` timestamp (oldest first). + # BatchRetrieveInventoryChanges is a catch-all query endpoint for queries + # that cannot be handled by other, simpler endpoints. + # @param [BatchRetrieveInventoryChangesRequest] body Required parameter: An + # object containing the fields to POST for the request. See the + # corresponding object definition for field details. + # @return [BatchRetrieveInventoryChangesResponse Hash] response from the API call + def batch_retrieve_inventory_changes(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/inventory/batch-retrieve-changes' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns current counts for the provided + # [CatalogObject](#type-catalogobject)s at the requested + # [Location](#type-location)s. + # Results are paginated and sorted in descending order according to their + # `calculated_at` timestamp (newest first). + # When `updated_after` is specified, only counts that have changed since + # that + # time (based on the server timestamp for the most recent change) are + # returned. This allows clients to perform a "sync" operation, for example + # in response to receiving a Webhook notification. + # @param [BatchRetrieveInventoryCountsRequest] body Required parameter: An + # object containing the fields to POST for the request. See the + # corresponding object definition for field details. + # @return [BatchRetrieveInventoryCountsResponse Hash] response from the API call + def batch_retrieve_inventory_counts(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/inventory/batch-retrieve-counts' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns the [InventoryPhysicalCount](#type-inventoryphysicalcount) + # object with the provided `physical_count_id`. + # @param [String] physical_count_id Required parameter: ID of the + # [InventoryPhysicalCount](#type-inventoryphysicalcount) to retrieve. + # @return [RetrieveInventoryPhysicalCountResponse Hash] response from the API call + def retrieve_inventory_physical_count(physical_count_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/inventory/physical-count/{physical_count_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'physical_count_id' => physical_count_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Retrieves the current calculated stock count for a given + # [CatalogObject](#type-catalogobject) at a given set of + # [Location](#type-location)s. Responses are paginated and unsorted. + # For more sophisticated queries, use a batch endpoint. + # @param [String] catalog_object_id Required parameter: ID of the + # [CatalogObject](#type-catalogobject) to retrieve. + # @param [String] location_ids Optional parameter: The + # [Location](#type-location) IDs to look up as a comma-separated list. An + # empty list queries all locations. + # @param [String] cursor Optional parameter: A pagination cursor returned by + # a previous call to this endpoint. Provide this to retrieve the next set of + # results for the original query. See + # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) + # for more information. + # @return [RetrieveInventoryCountResponse Hash] response from the API call + def retrieve_inventory_count(catalog_object_id:, + location_ids: nil, + cursor: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/inventory/{catalog_object_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'catalog_object_id' => catalog_object_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'location_ids' => location_ids, + 'cursor' => cursor + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a set of physical counts and inventory adjustments for the + # provided [CatalogObject](#type-catalogobject) at the requested + # [Location](#type-location)s. + # Results are paginated and sorted in descending order according to their + # `occurred_at` timestamp (newest first). + # There are no limits on how far back the caller can page. This endpoint is + # useful when displaying recent changes for a specific item. For more + # sophisticated queries, use a batch endpoint. + # @param [String] catalog_object_id Required parameter: ID of the + # [CatalogObject](#type-catalogobject) to retrieve. + # @param [String] location_ids Optional parameter: The + # [Location](#type-location) IDs to look up as a comma-separated list. An + # empty list queries all locations. + # @param [String] cursor Optional parameter: A pagination cursor returned by + # a previous call to this endpoint. Provide this to retrieve the next set of + # results for the original query. See + # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) + # for more information. + # @return [RetrieveInventoryChangesResponse Hash] response from the API call + def retrieve_inventory_changes(catalog_object_id:, + location_ids: nil, + cursor: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/inventory/{catalog_object_id}/changes' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'catalog_object_id' => catalog_object_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'location_ids' => location_ids, + 'cursor' => cursor + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/labor_api.rb b/lib/square/api/labor_api.rb index 4a7b91ab..227fc977 100644 --- a/lib/square/api/labor_api.rb +++ b/lib/square/api/labor_api.rb @@ -1,558 +1,558 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # LaborApi - class LaborApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Returns a paginated list of `BreakType` instances for a business. - # @param [String] location_id Optional parameter: Filter Break Types - # returned to only those that are associated with the specified location. - # @param [Integer] limit Optional parameter: Maximum number of Break Types - # to return per page. Can range between 1 and 200. The default is the - # maximum at 200. - # @param [String] cursor Optional parameter: Pointer to the next page of - # Break Type results to fetch. - # @return [ListBreakTypesResponse Hash] response from the API call - def list_break_types(location_id: nil, - limit: nil, - cursor: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/break-types' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'location_id' => location_id, - 'limit' => limit, - 'cursor' => cursor - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates a new `BreakType`. - # A `BreakType` is a template for creating `Break` objects. - # You must provide the following values in your request to this - # endpoint: - # - `location_id` - # - `break_name` - # - `expected_duration` - # - `is_paid` - # You can only have 3 `BreakType` instances per location. If you attempt to - # add a 4th - # `BreakType` for a location, an `INVALID_REQUEST_ERROR` "Exceeded limit of - # 3 breaks per location." - # is returned. - # @param [CreateBreakTypeRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [CreateBreakTypeResponse Hash] response from the API call - def create_break_type(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/break-types' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes an existing `BreakType`. - # A `BreakType` can be deleted even if it is referenced from a `Shift`. - # @param [String] id Required parameter: UUID for the `BreakType` being - # deleted. - # @return [DeleteBreakTypeResponse Hash] response from the API call - def delete_break_type(id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/break-types/{id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'id' => id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a single `BreakType` specified by id. - # @param [String] id Required parameter: UUID for the `BreakType` being - # retrieved. - # @return [GetBreakTypeResponse Hash] response from the API call - def get_break_type(id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/break-types/{id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'id' => id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Updates an existing `BreakType`. - # @param [String] id Required parameter: UUID for the `BreakType` being - # updated. - # @param [UpdateBreakTypeRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [UpdateBreakTypeResponse Hash] response from the API call - def update_break_type(id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/break-types/{id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'id' => id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a paginated list of `EmployeeWage` instances for a business. - # @param [String] employee_id Optional parameter: Filter wages returned to - # only those that are associated with the specified employee. - # @param [Integer] limit Optional parameter: Maximum number of Employee - # Wages to return per page. Can range between 1 and 200. The default is the - # maximum at 200. - # @param [String] cursor Optional parameter: Pointer to the next page of - # Employee Wage results to fetch. - # @return [ListEmployeeWagesResponse Hash] response from the API call - def list_employee_wages(employee_id: nil, - limit: nil, - cursor: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/employee-wages' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'employee_id' => employee_id, - 'limit' => limit, - 'cursor' => cursor - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a single `EmployeeWage` specified by id. - # @param [String] id Required parameter: UUID for the `EmployeeWage` being - # retrieved. - # @return [GetEmployeeWageResponse Hash] response from the API call - def get_employee_wage(id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/employee-wages/{id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'id' => id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates a new `Shift`. - # A `Shift` represents a complete work day for a single employee. - # You must provide the following values in your request to this - # endpoint: - # - `location_id` - # - `employee_id` - # - `start_at` - # An attempt to create a new `Shift` can result in a `BAD_REQUEST` error - # when: - # - The `status` of the new `Shift` is `OPEN` and the employee has another - # shift with an `OPEN` status. - # - The `start_at` date is in the future - # - the `start_at` or `end_at` overlaps another shift for the same employee - # - If `Break`s are set in the request, a break `start_at` - # must not be before the `Shift.start_at`. A break `end_at` must not be - # after - # the `Shift.end_at` - # @param [CreateShiftRequest] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @return [CreateShiftResponse Hash] response from the API call - def create_shift(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/shifts' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a paginated list of `Shift` records for a business. - # The list to be returned can be filtered by: - # - Location IDs **and** - # - employee IDs **and** - # - shift status (`OPEN`, `CLOSED`) **and** - # - shift start **and** - # - shift end **and** - # - work day details - # The list can be sorted by: - # - `start_at` - # - `end_at` - # - `created_at` - # - `updated_at` - # @param [SearchShiftsRequest] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @return [SearchShiftsResponse Hash] response from the API call - def search_shifts(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/shifts/search' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes a `Shift`. - # @param [String] id Required parameter: UUID for the `Shift` being - # deleted. - # @return [DeleteShiftResponse Hash] response from the API call - def delete_shift(id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/shifts/{id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'id' => id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a single `Shift` specified by id. - # @param [String] id Required parameter: UUID for the `Shift` being - # retrieved. - # @return [GetShiftResponse Hash] response from the API call - def get_shift(id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/shifts/{id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'id' => id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Updates an existing `Shift`. - # When adding a `Break` to a `Shift`, any earlier `Breaks` in the `Shift` - # have - # the `end_at` property set to a valid RFC-3339 datetime string. - # When closing a `Shift`, all `Break` instances in the shift must be - # complete with `end_at` - # set on each `Break`. - # @param [String] id Required parameter: ID of the object being updated. - # @param [UpdateShiftRequest] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @return [UpdateShiftResponse Hash] response from the API call - def update_shift(id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/shifts/{id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'id' => id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a list of `WorkweekConfig` instances for a business. - # @param [Integer] limit Optional parameter: Maximum number of Workweek - # Configs to return per page. - # @param [String] cursor Optional parameter: Pointer to the next page of - # Workweek Config results to fetch. - # @return [ListWorkweekConfigsResponse Hash] response from the API call - def list_workweek_configs(limit: nil, - cursor: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/workweek-configs' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'limit' => limit, - 'cursor' => cursor - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Updates a `WorkweekConfig`. - # @param [String] id Required parameter: UUID for the `WorkweekConfig` - # object being updated. - # @param [UpdateWorkweekConfigRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [UpdateWorkweekConfigResponse Hash] response from the API call - def update_workweek_config(id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/labor/workweek-configs/{id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'id' => id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # LaborApi + class LaborApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Returns a paginated list of `BreakType` instances for a business. + # @param [String] location_id Optional parameter: Filter Break Types + # returned to only those that are associated with the specified location. + # @param [Integer] limit Optional parameter: Maximum number of Break Types + # to return per page. Can range between 1 and 200. The default is the + # maximum at 200. + # @param [String] cursor Optional parameter: Pointer to the next page of + # Break Type results to fetch. + # @return [ListBreakTypesResponse Hash] response from the API call + def list_break_types(location_id: nil, + limit: nil, + cursor: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/break-types' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'location_id' => location_id, + 'limit' => limit, + 'cursor' => cursor + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates a new `BreakType`. + # A `BreakType` is a template for creating `Break` objects. + # You must provide the following values in your request to this + # endpoint: + # - `location_id` + # - `break_name` + # - `expected_duration` + # - `is_paid` + # You can only have 3 `BreakType` instances per location. If you attempt to + # add a 4th + # `BreakType` for a location, an `INVALID_REQUEST_ERROR` "Exceeded limit of + # 3 breaks per location." + # is returned. + # @param [CreateBreakTypeRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [CreateBreakTypeResponse Hash] response from the API call + def create_break_type(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/break-types' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes an existing `BreakType`. + # A `BreakType` can be deleted even if it is referenced from a `Shift`. + # @param [String] id Required parameter: UUID for the `BreakType` being + # deleted. + # @return [DeleteBreakTypeResponse Hash] response from the API call + def delete_break_type(id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/break-types/{id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'id' => id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a single `BreakType` specified by id. + # @param [String] id Required parameter: UUID for the `BreakType` being + # retrieved. + # @return [GetBreakTypeResponse Hash] response from the API call + def get_break_type(id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/break-types/{id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'id' => id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Updates an existing `BreakType`. + # @param [String] id Required parameter: UUID for the `BreakType` being + # updated. + # @param [UpdateBreakTypeRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [UpdateBreakTypeResponse Hash] response from the API call + def update_break_type(id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/break-types/{id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'id' => id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a paginated list of `EmployeeWage` instances for a business. + # @param [String] employee_id Optional parameter: Filter wages returned to + # only those that are associated with the specified employee. + # @param [Integer] limit Optional parameter: Maximum number of Employee + # Wages to return per page. Can range between 1 and 200. The default is the + # maximum at 200. + # @param [String] cursor Optional parameter: Pointer to the next page of + # Employee Wage results to fetch. + # @return [ListEmployeeWagesResponse Hash] response from the API call + def list_employee_wages(employee_id: nil, + limit: nil, + cursor: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/employee-wages' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'employee_id' => employee_id, + 'limit' => limit, + 'cursor' => cursor + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a single `EmployeeWage` specified by id. + # @param [String] id Required parameter: UUID for the `EmployeeWage` being + # retrieved. + # @return [GetEmployeeWageResponse Hash] response from the API call + def get_employee_wage(id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/employee-wages/{id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'id' => id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates a new `Shift`. + # A `Shift` represents a complete work day for a single employee. + # You must provide the following values in your request to this + # endpoint: + # - `location_id` + # - `employee_id` + # - `start_at` + # An attempt to create a new `Shift` can result in a `BAD_REQUEST` error + # when: + # - The `status` of the new `Shift` is `OPEN` and the employee has another + # shift with an `OPEN` status. + # - The `start_at` date is in the future + # - the `start_at` or `end_at` overlaps another shift for the same employee + # - If `Break`s are set in the request, a break `start_at` + # must not be before the `Shift.start_at`. A break `end_at` must not be + # after + # the `Shift.end_at` + # @param [CreateShiftRequest] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @return [CreateShiftResponse Hash] response from the API call + def create_shift(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/shifts' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a paginated list of `Shift` records for a business. + # The list to be returned can be filtered by: + # - Location IDs **and** + # - employee IDs **and** + # - shift status (`OPEN`, `CLOSED`) **and** + # - shift start **and** + # - shift end **and** + # - work day details + # The list can be sorted by: + # - `start_at` + # - `end_at` + # - `created_at` + # - `updated_at` + # @param [SearchShiftsRequest] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @return [SearchShiftsResponse Hash] response from the API call + def search_shifts(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/shifts/search' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes a `Shift`. + # @param [String] id Required parameter: UUID for the `Shift` being + # deleted. + # @return [DeleteShiftResponse Hash] response from the API call + def delete_shift(id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/shifts/{id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'id' => id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a single `Shift` specified by id. + # @param [String] id Required parameter: UUID for the `Shift` being + # retrieved. + # @return [GetShiftResponse Hash] response from the API call + def get_shift(id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/shifts/{id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'id' => id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Updates an existing `Shift`. + # When adding a `Break` to a `Shift`, any earlier `Breaks` in the `Shift` + # have + # the `end_at` property set to a valid RFC-3339 datetime string. + # When closing a `Shift`, all `Break` instances in the shift must be + # complete with `end_at` + # set on each `Break`. + # @param [String] id Required parameter: ID of the object being updated. + # @param [UpdateShiftRequest] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @return [UpdateShiftResponse Hash] response from the API call + def update_shift(id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/shifts/{id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'id' => id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a list of `WorkweekConfig` instances for a business. + # @param [Integer] limit Optional parameter: Maximum number of Workweek + # Configs to return per page. + # @param [String] cursor Optional parameter: Pointer to the next page of + # Workweek Config results to fetch. + # @return [ListWorkweekConfigsResponse Hash] response from the API call + def list_workweek_configs(limit: nil, + cursor: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/workweek-configs' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'limit' => limit, + 'cursor' => cursor + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Updates a `WorkweekConfig`. + # @param [String] id Required parameter: UUID for the `WorkweekConfig` + # object being updated. + # @param [UpdateWorkweekConfigRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [UpdateWorkweekConfigResponse Hash] response from the API call + def update_workweek_config(id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/labor/workweek-configs/{id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'id' => id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/locations_api.rb b/lib/square/api/locations_api.rb index 187a73a1..49290da5 100644 --- a/lib/square/api/locations_api.rb +++ b/lib/square/api/locations_api.rb @@ -1,45 +1,117 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # LocationsApi - class LocationsApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Provides the details for all of a business's locations. - # Most other Connect API endpoints have a required `location_id` path - # parameter. - # The `id` field of the [`Location`](#type-location) objects returned by - # this - # endpoint correspond to that `location_id` parameter. - # @return [ListLocationsResponse Hash] response from the API call - def list_locations - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # LocationsApi + class LocationsApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Provides the details for all of a business's locations. + # Most other Connect API endpoints have a required `location_id` path + # parameter. + # The `id` field of the [`Location`](#type-location) objects returned by + # this + # endpoint correspond to that `location_id` parameter. + # @return [ListLocationsResponse Hash] response from the API call + def list_locations + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Retrieves details of a location. + # @param [String] location_id Required parameter: The ID of the location to + # retrieve. + # @return [RetrieveLocationResponse Hash] response from the API call + def retrieve_location(location_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Updates the `Location` specified by the given ID. + # @param [String] location_id Required parameter: The ID of the location to + # update. + # @param [UpdateLocationRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [UpdateLocationResponse Hash] response from the API call + def update_location(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/merchants_api.rb b/lib/square/api/merchants_api.rb new file mode 100644 index 00000000..31bb5540 --- /dev/null +++ b/lib/square/api/merchants_api.rb @@ -0,0 +1,46 @@ +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # MerchantsApi + class MerchantsApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Retrieve a `Merchant` object for the given `merchant_id`. + # @param [String] merchant_id Required parameter: The ID of the merchant to + # retrieve + # @return [RetrieveMerchantResponse Hash] response from the API call + def retrieve_merchant(merchant_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/merchants/{merchant_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'merchant_id' => merchant_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/mobile_authorization_api.rb b/lib/square/api/mobile_authorization_api.rb index 0e89f144..69fb984d 100644 --- a/lib/square/api/mobile_authorization_api.rb +++ b/lib/square/api/mobile_authorization_api.rb @@ -1,56 +1,56 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # MobileAuthorizationApi - class MobileAuthorizationApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Generates code to authorize a mobile application to connect to a Square - # card reader - # Authorization codes are one-time-use and expire __60 minutes__ after being - # issued. - # __Important:__ The `Authorization` header you provide to this endpoint - # must have the following format: - # ``` - # Authorization: Bearer ACCESS_TOKEN - # ``` - # Replace `ACCESS_TOKEN` with a [valid production authorization - # credential](https://docs.connect.squareup.com/get-started#step-4-understan - # d-the-different-application-credentials). - # @param [CreateMobileAuthorizationCodeRequest] body Required parameter: An - # object containing the fields to POST for the request. See the - # corresponding object definition for field details. - # @return [CreateMobileAuthorizationCodeResponse Hash] response from the API call - def create_mobile_authorization_code(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/mobile/authorization-code' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # MobileAuthorizationApi + class MobileAuthorizationApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Generates code to authorize a mobile application to connect to a Square + # card reader + # Authorization codes are one-time-use and expire __60 minutes__ after being + # issued. + # __Important:__ The `Authorization` header you provide to this endpoint + # must have the following format: + # ``` + # Authorization: Bearer ACCESS_TOKEN + # ``` + # Replace `ACCESS_TOKEN` with a [valid production authorization + # credential](https://developer.squareup.com/docs/get-started#step-4-underst + # and-the-different-application-credentials). + # @param [CreateMobileAuthorizationCodeRequest] body Required parameter: An + # object containing the fields to POST for the request. See the + # corresponding object definition for field details. + # @return [CreateMobileAuthorizationCodeResponse Hash] response from the API call + def create_mobile_authorization_code(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/mobile/authorization-code' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/o_auth_api.rb b/lib/square/api/o_auth_api.rb index b78f43f1..4c8b41a2 100644 --- a/lib/square/api/o_auth_api.rb +++ b/lib/square/api/o_auth_api.rb @@ -1,168 +1,168 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # OAuthApi - class OAuthApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # `RenewToken` is deprecated. For information about refreshing OAuth access - # tokens, see - # [Renew OAuth - # Token](https://developer.squareup.com/docs/oauth-api/cookbook/renew-oauth- - # tokens). - # Renews an OAuth access token before it expires. - # OAuth access tokens besides your application's personal access token - # expire after __30 days__. - # You can also renew expired tokens within __15 days__ of their expiration. - # You cannot renew an access token that has been expired for more than 15 - # days. - # Instead, the associated user must re-complete the OAuth flow from the - # beginning. - # __Important:__ The `Authorization` header for this endpoint must have the - # following format: - # ``` - # Authorization: Client APPLICATION_SECRET - # ``` - # Replace `APPLICATION_SECRET` with the application secret on the - # Credentials - # page in the [application dashboard](https://connect.squareup.com/apps). - # @param [String] client_id Required parameter: Your application's ID, - # available from the [application - # dashboard](https://connect.squareup.com/apps). - # @param [RenewTokenRequest] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @param [String] authorization Required parameter: Client - # APPLICATION_SECRET - # @return [RenewTokenResponse Hash] response from the API call - def renew_token(client_id:, - body:, - authorization:) - warn 'Endpoint renew_token in OAuthApi is deprecated' - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/oauth2/clients/{client_id}/access-token/renew' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'client_id' => client_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8', - 'Authorization' => authorization - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Revokes an access token generated with the OAuth flow. - # If an account has more than one OAuth access token for your application, - # this - # endpoint revokes all of them, regardless of which token you specify. When - # an - # OAuth access token is revoked, all of the active subscriptions associated - # with that OAuth token are canceled immediately. - # __Important:__ The `Authorization` header for this endpoint must have the - # following format: - # ``` - # Authorization: Client APPLICATION_SECRET - # ``` - # Replace `APPLICATION_SECRET` with the application secret on the - # Credentials - # page in the [application dashboard](https://connect.squareup.com/apps). - # @param [RevokeTokenRequest] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @param [String] authorization Required parameter: Client - # APPLICATION_SECRET - # @return [RevokeTokenResponse Hash] response from the API call - def revoke_token(body:, - authorization:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/oauth2/revoke' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8', - 'Authorization' => authorization - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns an OAuth access token. - # The endpoint supports distinct methods of obtaining OAuth access tokens. - # Applications specify a method by adding the `grant_type` parameter - # in the request and also provide relevant information. - # For more information, see [OAuth access token - # management](https://developer.squareup.com/docs/authz/oauth/how-it-works#o - # auth-access-token-management). - # __Note:__ Regardless of the method application specified, - # the endpoint always returns two items; an OAuth access token and - # a refresh token in the response. - # __OAuth tokens should only live on secure servers. Application clients - # should never interact directly with OAuth tokens__. - # @param [ObtainTokenRequest] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @return [ObtainTokenResponse Hash] response from the API call - def obtain_token(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/oauth2/token' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # OAuthApi + class OAuthApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # `RenewToken` is deprecated. For information about refreshing OAuth access + # tokens, see + # [Renew OAuth + # Token](https://developer.squareup.com/docs/oauth-api/cookbook/renew-oauth- + # tokens). + # Renews an OAuth access token before it expires. + # OAuth access tokens besides your application's personal access token + # expire after __30 days__. + # You can also renew expired tokens within __15 days__ of their expiration. + # You cannot renew an access token that has been expired for more than 15 + # days. + # Instead, the associated user must re-complete the OAuth flow from the + # beginning. + # __Important:__ The `Authorization` header for this endpoint must have the + # following format: + # ``` + # Authorization: Client APPLICATION_SECRET + # ``` + # Replace `APPLICATION_SECRET` with the application secret on the + # Credentials + # page in the [application dashboard](https://connect.squareup.com/apps). + # @param [String] client_id Required parameter: Your application's ID, + # available from the [application + # dashboard](https://connect.squareup.com/apps). + # @param [RenewTokenRequest] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @param [String] authorization Required parameter: Client + # APPLICATION_SECRET + # @return [RenewTokenResponse Hash] response from the API call + def renew_token(client_id:, + body:, + authorization:) + warn 'Endpoint renew_token in OAuthApi is deprecated' + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/oauth2/clients/{client_id}/access-token/renew' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'client_id' => client_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8', + 'Authorization' => authorization + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Revokes an access token generated with the OAuth flow. + # If an account has more than one OAuth access token for your application, + # this + # endpoint revokes all of them, regardless of which token you specify. When + # an + # OAuth access token is revoked, all of the active subscriptions associated + # with that OAuth token are canceled immediately. + # __Important:__ The `Authorization` header for this endpoint must have the + # following format: + # ``` + # Authorization: Client APPLICATION_SECRET + # ``` + # Replace `APPLICATION_SECRET` with the application secret on the + # Credentials + # page in the [application dashboard](https://connect.squareup.com/apps). + # @param [RevokeTokenRequest] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @param [String] authorization Required parameter: Client + # APPLICATION_SECRET + # @return [RevokeTokenResponse Hash] response from the API call + def revoke_token(body:, + authorization:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/oauth2/revoke' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8', + 'Authorization' => authorization + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns an OAuth access token. + # The endpoint supports distinct methods of obtaining OAuth access tokens. + # Applications specify a method by adding the `grant_type` parameter + # in the request and also provide relevant information. + # For more information, see [OAuth access token + # management](https://developer.squareup.com/docs/authz/oauth/how-it-works#o + # auth-access-token-management). + # __Note:__ Regardless of the method application specified, + # the endpoint always returns two items; an OAuth access token and + # a refresh token in the response. + # __OAuth tokens should only live on secure servers. Application clients + # should never interact directly with OAuth tokens__. + # @param [ObtainTokenRequest] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @return [ObtainTokenResponse Hash] response from the API call + def obtain_token(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/oauth2/token' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/orders_api.rb b/lib/square/api/orders_api.rb index c3923c31..7da7b7a5 100644 --- a/lib/square/api/orders_api.rb +++ b/lib/square/api/orders_api.rb @@ -1,269 +1,271 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # OrdersApi - class OrdersApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Creates a new [Order](#type-order) which can include information on - # products for - # purchase and settings to apply to the purchase. - # To pay for a created order, please refer to the [Pay for - # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders) - # guide. - # You can modify open orders using the - # [UpdateOrder](#endpoint-orders-updateorder) endpoint. - # To learn more about the Orders API, see the - # [Orders API - # Overview](https://developer.squareup.com/docs/orders-api/what-it-does). - # @param [String] location_id Required parameter: The ID of the business - # location to associate the order with. - # @param [CreateOrderRequest] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @return [CreateOrderResponse Hash] response from the API call - def create_order(location_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/orders' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Retrieves a set of [Order](#type-order)s by their IDs. - # If a given Order ID does not exist, the ID is ignored instead of - # generating an error. - # @param [String] location_id Required parameter: The ID of the orders' - # associated location. - # @param [BatchRetrieveOrdersRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [BatchRetrieveOrdersResponse Hash] response from the API call - def batch_retrieve_orders(location_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/orders/batch-retrieve' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Updates an open [Order](#type-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](https://developer.squareup.com/docs/orders-api/manage-orders#sparse - # -order-objects) - # containing only the fields to update and the version the update is - # being applied to. - # - If deleting fields, the [dot notation - # paths](https://developer.squareup.com/docs/orders-api/manage-orders#on-dot - # -notation) - # identifying fields to clear. - # To pay for an order, please refer to the [Pay for - # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders) - # guide. - # To learn more about the Orders API, see the - # [Orders API - # Overview](https://developer.squareup.com/docs/orders-api/what-it-does). - # @param [UpdateOrderRequest] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @param [String] location_id Required parameter: Example: - # @param [String] order_id Required parameter: Example: - # @return [UpdateOrderResponse Hash] response from the API call - def update_order(body:, - location_id:, - order_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/orders/{order_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'order_id' => order_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # 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 (e.g. Point of Sale, Invoices, Connect APIs, etc). - # SearchOrders requests need to specify which locations to search and define - # a - # [`SearchOrdersQuery`](#type-searchordersquery) object which controls - # how to sort or filter the results. Your SearchOrdersQuery can: - # Set filter criteria. - # Set sort order. - # Determine whether to return results as complete Order objects, or as - # [OrderEntry](#type-orderentry) objects. - # Note that details for orders processed with Square Point of Sale while in - # offline mode may 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. - # @param [SearchOrdersRequest] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @return [SearchOrdersResponse Hash] response from the API call - def search_orders(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/orders/search' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Pay for an [order](#type-order) using one or more approved - # [payments](#type-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](#endpoint-payments-createpayment). - # Any approved payments that reference the same `order_id` not specified in - # the - # `payment_ids` will be canceled. - # - Be approved with [delayed - # capture](https://developer.squareup.com/docs/payments-api/take-payments#de - # layed-capture). - # Using a delayed capture payment with PayOrder will complete the approved - # payment. - # Learn how to [pay for orders with a single payment using the Payments - # API](https://developer.squareup.com/docs/orders-api/pay-for-orders). - # @param [String] order_id Required parameter: The ID of the order being - # paid. - # @param [PayOrderRequest] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [PayOrderResponse Hash] response from the API call - def pay_order(order_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/orders/{order_id}/pay' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'order_id' => order_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # OrdersApi + class OrdersApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Creates a new [Order](#type-order) which can include information on + # products for + # purchase and settings to apply to the purchase. + # To pay for a created order, please refer to the [Pay for + # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders) + # guide. + # You can modify open orders using the + # [UpdateOrder](#endpoint-orders-updateorder) endpoint. + # To learn more about the Orders API, see the + # [Orders API + # Overview](https://developer.squareup.com/docs/orders-api/what-it-does). + # @param [String] location_id Required parameter: The ID of the business + # location to associate the order with. + # @param [CreateOrderRequest] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @return [CreateOrderResponse Hash] response from the API call + def create_order(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/orders' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Retrieves a set of [Order](#type-order)s by their IDs. + # If a given Order ID does not exist, the ID is ignored instead of + # generating an error. + # @param [String] location_id Required parameter: The ID of the orders' + # associated location. + # @param [BatchRetrieveOrdersRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [BatchRetrieveOrdersResponse Hash] response from the API call + def batch_retrieve_orders(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/orders/batch-retrieve' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Updates an open [Order](#type-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](https://developer.squareup.com/docs/orders-api/manage-orders#sparse + # -order-objects) + # containing only the fields to update and the version the update is + # being applied to. + # - If deleting fields, the [dot notation + # paths](https://developer.squareup.com/docs/orders-api/manage-orders#on-dot + # -notation) + # identifying fields to clear. + # To pay for an order, please refer to the [Pay for + # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders) + # guide. + # To learn more about the Orders API, see the + # [Orders API + # Overview](https://developer.squareup.com/docs/orders-api/what-it-does). + # @param [String] location_id Required parameter: The ID of the order's + # associated location. + # @param [String] order_id Required parameter: The ID of the order to + # update. + # @param [UpdateOrderRequest] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @return [UpdateOrderResponse Hash] response from the API call + def update_order(location_id:, + order_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/orders/{order_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'order_id' => order_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # 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 (e.g. Point of Sale, Invoices, Connect APIs, etc). + # SearchOrders requests need to specify which locations to search and define + # a + # [`SearchOrdersQuery`](#type-searchordersquery) object which controls + # how to sort or filter the results. Your SearchOrdersQuery can: + # Set filter criteria. + # Set sort order. + # Determine whether to return results as complete Order objects, or as + # [OrderEntry](#type-orderentry) objects. + # Note that details for orders processed with Square Point of Sale while in + # offline mode may 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. + # @param [SearchOrdersRequest] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @return [SearchOrdersResponse Hash] response from the API call + def search_orders(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/orders/search' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Pay for an [order](#type-order) using one or more approved + # [payments](#type-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](#endpoint-payments-createpayment). + # Any approved payments that reference the same `order_id` not specified in + # the + # `payment_ids` will be canceled. + # - Be approved with [delayed + # capture](https://developer.squareup.com/docs/payments-api/take-payments#de + # layed-capture). + # Using a delayed capture payment with PayOrder will complete the approved + # payment. + # Learn how to [pay for orders with a single payment using the Payments + # API](https://developer.squareup.com/docs/orders-api/pay-for-orders). + # @param [String] order_id Required parameter: The ID of the order being + # paid. + # @param [PayOrderRequest] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [PayOrderResponse Hash] response from the API call + def pay_order(order_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/orders/{order_id}/pay' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'order_id' => order_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/payments_api.rb b/lib/square/api/payments_api.rb index 0834a7a9..8419876b 100644 --- a/lib/square/api/payments_api.rb +++ b/lib/square/api/payments_api.rb @@ -1,282 +1,282 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # PaymentsApi - class PaymentsApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Retrieves a list of payments taken by the account making the request. - # Max results per page: 100 - # @param [String] begin_time Optional parameter: Timestamp for the beginning - # of the reporting period, in RFC 3339 format. Inclusive. Default: The - # current time minus one year. - # @param [String] end_time Optional parameter: Timestamp for the end of the - # requested reporting period, in RFC 3339 format. Default: The current - # time. - # @param [String] sort_order Optional parameter: The order in which results - # are listed. - `ASC` - oldest to newest - `DESC` - newest to oldest - # (default). - # @param [String] cursor Optional parameter: A pagination cursor returned by - # a previous call to this endpoint. Provide this to retrieve the next set of - # results for the original query. See - # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) - # for more information. - # @param [String] location_id Optional parameter: ID of location associated - # with payment - # @param [Long] total Optional parameter: The exact amount in the - # total_money for a `Payment`. - # @param [String] last_4 Optional parameter: The last 4 digits of `Payment` - # card. - # @param [String] card_brand Optional parameter: The brand of `Payment` - # card. For example, `VISA` - # @return [ListPaymentsResponse Hash] response from the API call - def list_payments(begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil, - location_id: nil, - total: nil, - last_4: nil, - card_brand: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/payments' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'begin_time' => begin_time, - 'end_time' => end_time, - 'sort_order' => sort_order, - 'cursor' => cursor, - 'location_id' => location_id, - 'total' => total, - 'last_4' => last_4, - 'card_brand' => card_brand - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Charges a payment source, for example, a card - # represented by customer's card on file or a card nonce. In addition - # to the payment source, the request must also include the - # amount to accept for the payment. - # There are several optional parameters that you can include in the request. - # For example, tip money, whether to autocomplete the payment, or a - # reference ID - # to correlate this payment with another system. - # For more information about these - # payment options, see [Take - # Payments](https://developer.squareup.com/docs/payments-api/take-payments). - # The `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required - # to enable application fees. - # @param [CreatePaymentRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [CreatePaymentResponse Hash] response from the API call - def create_payment(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/payments' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Cancels a payment identified by the idenpotency key that is specified the - # request. - # Use this method when status of a CreatePayment request is unknown. - # For example, after you send a CreatePayment - # request a network error occurs and you don't get a response. In this case, - # you can direct - # Square to cancel the payment using this endpoint. In the request, you - # provide the same idempotency - # key that you provided in your CreatePayment request you want to cancel. - # After cancelling the - # payment, you can submit your CreatePayment request again. - # Note that if no payment with the specified idempotency key is found, no - # action is taken, the end - # point returns successfully. - # @param [CancelPaymentByIdempotencyKeyRequest] body Required parameter: An - # object containing the fields to POST for the request. See the - # corresponding object definition for field details. - # @return [CancelPaymentByIdempotencyKeyResponse Hash] response from the API call - def cancel_payment_by_idempotency_key(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/payments/cancel' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Retrieves details for a specific Payment. - # @param [String] payment_id Required parameter: Unique ID for the desired - # `Payment`. - # @return [GetPaymentResponse Hash] response from the API call - def get_payment(payment_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/payments/{payment_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'payment_id' => payment_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Cancels a payment. If you set `autocomplete` to false when creating a - # payment, - # you can cancel the payment using this endpoint. For more information, see - # [Delayed - # Payments](https://developer.squareup.com/docs/payments-api/take-payments#d - # elayed-payments). - # @param [String] payment_id Required parameter: `payment_id` identifying - # the payment to be canceled. - # @return [CancelPaymentResponse Hash] response from the API call - def cancel_payment(payment_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/payments/{payment_id}/cancel' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'payment_id' => payment_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Completes a payment. - # By default, payments are set to complete immediately after they are - # created. - # If you set autocomplete to false when creating a payment, - # you can complete the payment using this endpoint. For more information, - # see - # [Delayed - # Payments](https://developer.squareup.com/docs/payments-api/take-payments#d - # elayed-payments). - # @param [String] payment_id Required parameter: Unique ID identifying the - # payment to be completed. - # @return [CompletePaymentResponse Hash] response from the API call - def complete_payment(payment_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/payments/{payment_id}/complete' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'payment_id' => payment_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # PaymentsApi + class PaymentsApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Retrieves a list of payments taken by the account making the request. + # Max results per page: 100 + # @param [String] begin_time Optional parameter: Timestamp for the beginning + # of the reporting period, in RFC 3339 format. Inclusive. Default: The + # current time minus one year. + # @param [String] end_time Optional parameter: Timestamp for the end of the + # requested reporting period, in RFC 3339 format. Default: The current + # time. + # @param [String] sort_order Optional parameter: The order in which results + # are listed. - `ASC` - oldest to newest - `DESC` - newest to oldest + # (default). + # @param [String] cursor Optional parameter: A pagination cursor returned by + # a previous call to this endpoint. Provide this to retrieve the next set of + # results for the original query. See + # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) + # for more information. + # @param [String] location_id Optional parameter: ID of location associated + # with payment + # @param [Long] total Optional parameter: The exact amount in the + # total_money for a `Payment`. + # @param [String] last_4 Optional parameter: The last 4 digits of `Payment` + # card. + # @param [String] card_brand Optional parameter: The brand of `Payment` + # card. For example, `VISA` + # @return [ListPaymentsResponse Hash] response from the API call + def list_payments(begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil, + location_id: nil, + total: nil, + last_4: nil, + card_brand: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/payments' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'begin_time' => begin_time, + 'end_time' => end_time, + 'sort_order' => sort_order, + 'cursor' => cursor, + 'location_id' => location_id, + 'total' => total, + 'last_4' => last_4, + 'card_brand' => card_brand + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Charges a payment source, for example, a card + # represented by customer's card on file or a card nonce. In addition + # to the payment source, the request must also include the + # amount to accept for the payment. + # There are several optional parameters that you can include in the request. + # For example, tip money, whether to autocomplete the payment, or a + # reference ID + # to correlate this payment with another system. + # For more information about these + # payment options, see [Take + # Payments](https://developer.squareup.com/docs/payments-api/take-payments). + # The `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required + # to enable application fees. + # @param [CreatePaymentRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [CreatePaymentResponse Hash] response from the API call + def create_payment(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/payments' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Cancels (voids) a payment identified by the idempotency key that is + # specified in the request. + # Use this method when status of a CreatePayment request is unknown. + # For example, after you send a CreatePayment + # request a network error occurs and you don't get a response. In this case, + # you can direct + # Square to cancel the payment using this endpoint. In the request, you + # provide the same idempotency + # key that you provided in your CreatePayment request you want to cancel. + # After cancelling the + # payment, you can submit your CreatePayment request again. + # Note that if no payment with the specified idempotency key is found, no + # action is taken, the end + # point returns successfully. + # @param [CancelPaymentByIdempotencyKeyRequest] body Required parameter: An + # object containing the fields to POST for the request. See the + # corresponding object definition for field details. + # @return [CancelPaymentByIdempotencyKeyResponse Hash] response from the API call + def cancel_payment_by_idempotency_key(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/payments/cancel' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Retrieves details for a specific Payment. + # @param [String] payment_id Required parameter: Unique ID for the desired + # `Payment`. + # @return [GetPaymentResponse Hash] response from the API call + def get_payment(payment_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/payments/{payment_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'payment_id' => payment_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Cancels (voids) a payment. If you set `autocomplete` to false when + # creating a payment, + # you can cancel the payment using this endpoint. For more information, see + # [Delayed + # Payments](https://developer.squareup.com/docs/payments-api/take-payments#d + # elayed-payments). + # @param [String] payment_id Required parameter: `payment_id` identifying + # the payment to be canceled. + # @return [CancelPaymentResponse Hash] response from the API call + def cancel_payment(payment_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/payments/{payment_id}/cancel' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'payment_id' => payment_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Completes (captures) a payment. + # By default, payments are set to complete immediately after they are + # created. + # If you set autocomplete to false when creating a payment, you can complete + # (capture) + # the payment using this endpoint. For more information, see + # [Delayed + # Payments](https://developer.squareup.com/docs/payments-api/take-payments#d + # elayed-payments). + # @param [String] payment_id Required parameter: Unique ID identifying the + # payment to be completed. + # @return [CompletePaymentResponse Hash] response from the API call + def complete_payment(payment_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/payments/{payment_id}/complete' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'payment_id' => payment_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/refunds_api.rb b/lib/square/api/refunds_api.rb index 99acc98e..3dd0e2e1 100644 --- a/lib/square/api/refunds_api.rb +++ b/lib/square/api/refunds_api.rb @@ -1,149 +1,149 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # RefundsApi - class RefundsApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Retrieves a list of refunds for the account making the request. - # Max results per page: 100 - # @param [String] begin_time Optional parameter: Timestamp for the beginning - # of the requested reporting period, in RFC 3339 format. Default: The - # current time minus one year. - # @param [String] end_time Optional parameter: Timestamp for the end of the - # requested reporting period, in RFC 3339 format. Default: The current - # time. - # @param [String] sort_order Optional parameter: The order in which results - # are listed. - `ASC` - oldest to newest - `DESC` - newest to oldest - # (default). - # @param [String] cursor Optional parameter: A pagination cursor returned by - # a previous call to this endpoint. Provide this to retrieve the next set of - # results for the original query. See - # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) - # for more information. - # @param [String] location_id Optional parameter: ID of location associated - # with payment. - # @param [String] status Optional parameter: If provided, only refunds with - # the given status are returned. For a list of refund status values, see - # [PaymentRefund](#type-paymentrefund). Default: If omitted refunds are - # returned regardless of status. - # @param [String] source_type Optional parameter: If provided, only refunds - # with the given source type are returned. - `CARD` - List refunds only for - # payments where card was specified as payment source. Default: If omitted - # refunds are returned regardless of source type. - # @return [ListPaymentRefundsResponse Hash] response from the API call - def list_payment_refunds(begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil, - location_id: nil, - status: nil, - source_type: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/refunds' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'begin_time' => begin_time, - 'end_time' => end_time, - 'sort_order' => sort_order, - 'cursor' => cursor, - 'location_id' => location_id, - 'status' => status, - 'source_type' => source_type - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Refunds a payment. You can refund the entire payment amount or a - # portion of it. For more information, see - # [Payments and Refunds - # Overview](https://developer.squareup.com/docs/payments-api/overview). - # @param [RefundPaymentRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [RefundPaymentResponse Hash] response from the API call - def refund_payment(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/refunds' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Retrieves a specific `Refund` using the `refund_id`. - # @param [String] refund_id Required parameter: Unique ID for the desired - # `PaymentRefund`. - # @return [GetPaymentRefundResponse Hash] response from the API call - def get_payment_refund(refund_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/refunds/{refund_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'refund_id' => refund_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # RefundsApi + class RefundsApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Retrieves a list of refunds for the account making the request. + # Max results per page: 100 + # @param [String] begin_time Optional parameter: Timestamp for the beginning + # of the requested reporting period, in RFC 3339 format. Default: The + # current time minus one year. + # @param [String] end_time Optional parameter: Timestamp for the end of the + # requested reporting period, in RFC 3339 format. Default: The current + # time. + # @param [String] sort_order Optional parameter: The order in which results + # are listed. - `ASC` - oldest to newest - `DESC` - newest to oldest + # (default). + # @param [String] cursor Optional parameter: A pagination cursor returned by + # a previous call to this endpoint. Provide this to retrieve the next set of + # results for the original query. See + # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) + # for more information. + # @param [String] location_id Optional parameter: ID of location associated + # with payment. + # @param [String] status Optional parameter: If provided, only refunds with + # the given status are returned. For a list of refund status values, see + # [PaymentRefund](#type-paymentrefund). Default: If omitted refunds are + # returned regardless of status. + # @param [String] source_type Optional parameter: If provided, only refunds + # with the given source type are returned. - `CARD` - List refunds only for + # payments where card was specified as payment source. Default: If omitted + # refunds are returned regardless of source type. + # @return [ListPaymentRefundsResponse Hash] response from the API call + def list_payment_refunds(begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil, + location_id: nil, + status: nil, + source_type: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/refunds' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'begin_time' => begin_time, + 'end_time' => end_time, + 'sort_order' => sort_order, + 'cursor' => cursor, + 'location_id' => location_id, + 'status' => status, + 'source_type' => source_type + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Refunds a payment. You can refund the entire payment amount or a + # portion of it. For more information, see + # [Payments and Refunds + # Overview](https://developer.squareup.com/docs/payments-api/overview). + # @param [RefundPaymentRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [RefundPaymentResponse Hash] response from the API call + def refund_payment(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/refunds' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Retrieves a specific `Refund` using the `refund_id`. + # @param [String] refund_id Required parameter: Unique ID for the desired + # `PaymentRefund`. + # @return [GetPaymentRefundResponse Hash] response from the API call + def get_payment_refund(refund_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/refunds/{refund_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'refund_id' => refund_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/reporting_api.rb b/lib/square/api/reporting_api.rb index 9f245bf0..a1accbdb 100644 --- a/lib/square/api/reporting_api.rb +++ b/lib/square/api/reporting_api.rb @@ -1,143 +1,145 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # ReportingApi - class ReportingApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Returns a list of refunded transactions (across all possible originating - # locations) relating to monies - # credited to the provided location ID by another Square account using the - # `additional_recipients` field in a transaction. - # Max results per [page](#paginatingresults): 50 - # @param [String] location_id Required parameter: The ID of the location to - # list AdditionalRecipientReceivableRefunds for. - # @param [String] begin_time Optional parameter: The beginning of the - # requested reporting period, in RFC 3339 format. See [Date - # ranges](#dateranges) for details on date inclusivity/exclusivity. Default - # value: The current time minus one year. - # @param [String] end_time Optional parameter: The end of the requested - # reporting period, in RFC 3339 format. See [Date ranges](#dateranges) for - # details on date inclusivity/exclusivity. Default value: The current - # time. - # @param [SortOrder] sort_order Optional parameter: The order in which - # results are listed in the response (`ASC` for oldest first, `DESC` for - # newest first). Default value: `DESC` - # @param [String] cursor Optional parameter: A pagination cursor returned by - # a previous call to this endpoint. Provide this to retrieve the next set of - # results for your original query. See - # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) - # for more information. - # @return [ListAdditionalRecipientReceivableRefundsResponse Hash] response from the API call - def list_additional_recipient_receivable_refunds(location_id:, - begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil) - warn 'Endpoint list_additional_recipient_receivable_refunds in ReportingApi is deprecated' - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/additional-recipient-receivable-refunds' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'begin_time' => begin_time, - 'end_time' => end_time, - 'sort_order' => sort_order, - 'cursor' => cursor - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Returns a list of receivables (across all possible sending locations) - # representing monies credited - # to the provided location ID by another Square account using the - # `additional_recipients` field in a transaction. - # Max results per [page](#paginatingresults): 50 - # @param [String] location_id Required parameter: The ID of the location to - # list AdditionalRecipientReceivables for. - # @param [String] begin_time Optional parameter: The beginning of the - # requested reporting period, in RFC 3339 format. See [Date - # ranges](#dateranges) for details on date inclusivity/exclusivity. Default - # value: The current time minus one year. - # @param [String] end_time Optional parameter: The end of the requested - # reporting period, in RFC 3339 format. See [Date ranges](#dateranges) for - # details on date inclusivity/exclusivity. Default value: The current - # time. - # @param [SortOrder] sort_order Optional parameter: The order in which - # results are listed in the response (`ASC` for oldest first, `DESC` for - # newest first). Default value: `DESC` - # @param [String] cursor Optional parameter: A pagination cursor returned by - # a previous call to this endpoint. Provide this to retrieve the next set of - # results for your original query. See - # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) - # for more information. - # @return [ListAdditionalRecipientReceivablesResponse Hash] response from the API call - def list_additional_recipient_receivables(location_id:, - begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil) - warn 'Endpoint list_additional_recipient_receivables in ReportingApi is deprecated' - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/additional-recipient-receivables' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'begin_time' => begin_time, - 'end_time' => end_time, - 'sort_order' => sort_order, - 'cursor' => cursor - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # ReportingApi + class ReportingApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Returns a list of refunded transactions (across all possible originating + # locations) relating to monies + # credited to the provided location ID by another Square account using the + # `additional_recipients` field in a transaction. + # Max results per [page](#paginatingresults): 50 + # @param [String] location_id Required parameter: The ID of the location to + # list AdditionalRecipientReceivableRefunds for. + # @param [String] begin_time Optional parameter: The beginning of the + # requested reporting period, in RFC 3339 format. See [Date + # ranges](#dateranges) for details on date inclusivity/exclusivity. Default + # value: The current time minus one year. + # @param [String] end_time Optional parameter: The end of the requested + # reporting period, in RFC 3339 format. See [Date ranges](#dateranges) for + # details on date inclusivity/exclusivity. Default value: The current + # time. + # @param [SortOrder] sort_order Optional parameter: The order in which + # results are listed in the response (`ASC` for oldest first, `DESC` for + # newest first). Default value: `DESC` + # @param [String] cursor Optional parameter: A pagination cursor returned by + # a previous call to this endpoint. Provide this to retrieve the next set of + # results for your original query. See + # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) + # for more information. + # @return [ListAdditionalRecipientReceivableRefundsResponse Hash] response from the API call + def list_additional_recipient_receivable_refunds(location_id:, + begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil) + warn 'Endpoint list_additional_recipient_receivable_refunds in Reporting'\ + 'Api is deprecated' + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/additional-recipient-receivable-refunds' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'begin_time' => begin_time, + 'end_time' => end_time, + 'sort_order' => sort_order, + 'cursor' => cursor + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Returns a list of receivables (across all possible sending locations) + # representing monies credited + # to the provided location ID by another Square account using the + # `additional_recipients` field in a transaction. + # Max results per [page](#paginatingresults): 50 + # @param [String] location_id Required parameter: The ID of the location to + # list AdditionalRecipientReceivables for. + # @param [String] begin_time Optional parameter: The beginning of the + # requested reporting period, in RFC 3339 format. See [Date + # ranges](#dateranges) for details on date inclusivity/exclusivity. Default + # value: The current time minus one year. + # @param [String] end_time Optional parameter: The end of the requested + # reporting period, in RFC 3339 format. See [Date ranges](#dateranges) for + # details on date inclusivity/exclusivity. Default value: The current + # time. + # @param [SortOrder] sort_order Optional parameter: The order in which + # results are listed in the response (`ASC` for oldest first, `DESC` for + # newest first). Default value: `DESC` + # @param [String] cursor Optional parameter: A pagination cursor returned by + # a previous call to this endpoint. Provide this to retrieve the next set of + # results for your original query. See + # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) + # for more information. + # @return [ListAdditionalRecipientReceivablesResponse Hash] response from the API call + def list_additional_recipient_receivables(location_id:, + begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil) + warn 'Endpoint list_additional_recipient_receivables in ReportingApi is '\ + 'deprecated' + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/additional-recipient-receivables' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'begin_time' => begin_time, + 'end_time' => end_time, + 'sort_order' => sort_order, + 'cursor' => cursor + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/transactions_api.rb b/lib/square/api/transactions_api.rb index 9b7aedab..2bd93e66 100644 --- a/lib/square/api/transactions_api.rb +++ b/lib/square/api/transactions_api.rb @@ -1,379 +1,379 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # TransactionsApi - class TransactionsApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Lists refunds for one of a business's locations. - # Deprecated - recommend using [SearchOrders](#endpoint-orders-searchorders) - # In addition to full or partial tender refunds processed through Square - # APIs, - # refunds may result from itemized returns or exchanges through Square's - # Point of Sale applications. - # Refunds with a `status` of `PENDING` are not currently included in this - # endpoint's response. - # Max results per [page](#paginatingresults): 50 - # @param [String] location_id Required parameter: The ID of the location to - # list refunds for. - # @param [String] begin_time Optional parameter: The beginning of the - # requested reporting period, in RFC 3339 format. See [Date - # ranges](#dateranges) for details on date inclusivity/exclusivity. Default - # value: The current time minus one year. - # @param [String] end_time Optional parameter: The end of the requested - # reporting period, in RFC 3339 format. See [Date ranges](#dateranges) for - # details on date inclusivity/exclusivity. Default value: The current - # time. - # @param [SortOrder] sort_order Optional parameter: The order in which - # results are listed in the response (`ASC` for oldest first, `DESC` for - # newest first). Default value: `DESC` - # @param [String] cursor Optional parameter: A pagination cursor returned by - # a previous call to this endpoint. Provide this to retrieve the next set of - # results for your original query. See - # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) - # for more information. - # @return [ListRefundsResponse Hash] response from the API call - def list_refunds(location_id:, - begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil) - warn 'Endpoint list_refunds in TransactionsApi is deprecated' - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/refunds' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'begin_time' => begin_time, - 'end_time' => end_time, - 'sort_order' => sort_order, - 'cursor' => cursor - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Lists transactions for a particular location. - # Deprecated - recommend using [SearchOrders](#endpoint-orders-searchorders) - # Transactions include payment information from sales and exchanges and - # refund - # information from returns and exchanges. - # Max results per [page](#paginatingresults): 50 - # @param [String] location_id Required parameter: The ID of the location to - # list transactions for. - # @param [String] begin_time Optional parameter: The beginning of the - # requested reporting period, in RFC 3339 format. See [Date - # ranges](#dateranges) for details on date inclusivity/exclusivity. Default - # value: The current time minus one year. - # @param [String] end_time Optional parameter: The end of the requested - # reporting period, in RFC 3339 format. See [Date ranges](#dateranges) for - # details on date inclusivity/exclusivity. Default value: The current - # time. - # @param [SortOrder] sort_order Optional parameter: The order in which - # results are listed in the response (`ASC` for oldest first, `DESC` for - # newest first). Default value: `DESC` - # @param [String] cursor Optional parameter: A pagination cursor returned by - # a previous call to this endpoint. Provide this to retrieve the next set of - # results for your original query. See - # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) - # for more information. - # @return [ListTransactionsResponse Hash] response from the API call - def list_transactions(location_id:, - begin_time: nil, - end_time: nil, - sort_order: nil, - cursor: nil) - warn 'Endpoint list_transactions in TransactionsApi is deprecated' - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/transactions' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'begin_time' => begin_time, - 'end_time' => end_time, - 'sort_order' => sort_order, - 'cursor' => cursor - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Charges a card represented by a card nonce or a customer's card on file. - # Deprecated - recommend using - # [CreatePayment](#endpoint-payments-createpayment) - # Your request to this endpoint must include _either_: - # - A value for the `card_nonce` parameter (to charge a card nonce generated - # with the `SqPaymentForm`) - # - Values for the `customer_card_id` and `customer_id` parameters (to - # charge - # a customer's card on file) - # When this response is returned, the amount of Square's processing fee - # might not yet be - # calculated. To obtain the processing fee, wait about ten seconds and call - # [RetrieveTransaction](#endpoint-transactions-retrievetransaction). See the - # `processing_fee_money` - # field of each [Tender included](#type-tender) in the transaction. - # @param [String] location_id Required parameter: The ID of the location to - # associate the created transaction with. - # @param [ChargeRequest] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [ChargeResponse Hash] response from the API call - def charge(location_id:, - body:) - warn 'Endpoint charge in TransactionsApi is deprecated' - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/transactions' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Retrieves details for a single transaction. - # Deprecated - recommend using - # [BatchRetrieveOrders](#endpoint-batchretrieveorders) - # @param [String] location_id Required parameter: The ID of the - # transaction's associated location. - # @param [String] transaction_id Required parameter: The ID of the - # transaction to retrieve. - # @return [RetrieveTransactionResponse Hash] response from the API call - def retrieve_transaction(location_id:, - transaction_id:) - warn 'Endpoint retrieve_transaction in TransactionsApi is deprecated' - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/transactions/{transaction_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'transaction_id' => transaction_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Captures a transaction that was created with the - # [Charge](#endpoint-transactions-charge) - # endpoint with a `delay_capture` value of `true`. - # See the [Delay Capture of - # Funds](https://developer.squareup.com/docs/transactions-api/cookbook/delay - # -capture) - # recipe for more information. - # @param [String] location_id Required parameter: Example: - # @param [String] transaction_id Required parameter: Example: - # @return [CaptureTransactionResponse Hash] response from the API call - def capture_transaction(location_id:, - transaction_id:) - warn 'Endpoint capture_transaction in TransactionsApi is deprecated' - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/transactions/{transaction_id}/capture' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'transaction_id' => transaction_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Initiates a refund for a previously charged tender. - # Deprecated - recommend using - # [RefundPayment](#endpoint-refunds-refundpayment) - # You must issue a refund within 120 days of the associated payment. See - # [this article](https://squareup.com/help/us/en/article/5060) for more - # information - # on refund behavior. - # NOTE: Card-present transactions with Interac credit cards **cannot be - # refunded using the Connect API**. Interac transactions must refunded - # in-person (e.g., dipping the card using POS app). - # @param [String] location_id Required parameter: The ID of the original - # transaction's associated location. - # @param [String] transaction_id Required parameter: The ID of the original - # transaction that includes the tender to refund. - # @param [CreateRefundRequest] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @return [CreateRefundResponse Hash] response from the API call - def create_refund(location_id:, - transaction_id:, - body:) - warn 'Endpoint create_refund in TransactionsApi is deprecated' - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/transactions/{transaction_id}/refund' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'transaction_id' => transaction_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Cancels a transaction that was created with the - # [Charge](#endpoint-transactions-charge) - # endpoint with a `delay_capture` value of `true`. - # See the [Delay Capture of - # Funds](https://developer.squareup.com/docs/transactions-api/cookbook/delay - # -capture) - # recipe for more information. - # @param [String] location_id Required parameter: Example: - # @param [String] transaction_id Required parameter: Example: - # @return [VoidTransactionResponse Hash] response from the API call - def void_transaction(location_id:, - transaction_id:) - warn 'Endpoint void_transaction in TransactionsApi is deprecated' - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v2/locations/{location_id}/transactions/{transaction_id}/void' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'transaction_id' => transaction_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # TransactionsApi + class TransactionsApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Lists refunds for one of a business's locations. + # Deprecated - recommend using [SearchOrders](#endpoint-orders-searchorders) + # In addition to full or partial tender refunds processed through Square + # APIs, + # refunds may result from itemized returns or exchanges through Square's + # Point of Sale applications. + # Refunds with a `status` of `PENDING` are not currently included in this + # endpoint's response. + # Max results per [page](#paginatingresults): 50 + # @param [String] location_id Required parameter: The ID of the location to + # list refunds for. + # @param [String] begin_time Optional parameter: The beginning of the + # requested reporting period, in RFC 3339 format. See [Date + # ranges](#dateranges) for details on date inclusivity/exclusivity. Default + # value: The current time minus one year. + # @param [String] end_time Optional parameter: The end of the requested + # reporting period, in RFC 3339 format. See [Date ranges](#dateranges) for + # details on date inclusivity/exclusivity. Default value: The current + # time. + # @param [SortOrder] sort_order Optional parameter: The order in which + # results are listed in the response (`ASC` for oldest first, `DESC` for + # newest first). Default value: `DESC` + # @param [String] cursor Optional parameter: A pagination cursor returned by + # a previous call to this endpoint. Provide this to retrieve the next set of + # results for your original query. See + # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) + # for more information. + # @return [ListRefundsResponse Hash] response from the API call + def list_refunds(location_id:, + begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil) + warn 'Endpoint list_refunds in TransactionsApi is deprecated' + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/refunds' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'begin_time' => begin_time, + 'end_time' => end_time, + 'sort_order' => sort_order, + 'cursor' => cursor + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Lists transactions for a particular location. + # Deprecated - recommend using [SearchOrders](#endpoint-orders-searchorders) + # Transactions include payment information from sales and exchanges and + # refund + # information from returns and exchanges. + # Max results per [page](#paginatingresults): 50 + # @param [String] location_id Required parameter: The ID of the location to + # list transactions for. + # @param [String] begin_time Optional parameter: The beginning of the + # requested reporting period, in RFC 3339 format. See [Date + # ranges](#dateranges) for details on date inclusivity/exclusivity. Default + # value: The current time minus one year. + # @param [String] end_time Optional parameter: The end of the requested + # reporting period, in RFC 3339 format. See [Date ranges](#dateranges) for + # details on date inclusivity/exclusivity. Default value: The current + # time. + # @param [SortOrder] sort_order Optional parameter: The order in which + # results are listed in the response (`ASC` for oldest first, `DESC` for + # newest first). Default value: `DESC` + # @param [String] cursor Optional parameter: A pagination cursor returned by + # a previous call to this endpoint. Provide this to retrieve the next set of + # results for your original query. See + # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) + # for more information. + # @return [ListTransactionsResponse Hash] response from the API call + def list_transactions(location_id:, + begin_time: nil, + end_time: nil, + sort_order: nil, + cursor: nil) + warn 'Endpoint list_transactions in TransactionsApi is deprecated' + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/transactions' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'begin_time' => begin_time, + 'end_time' => end_time, + 'sort_order' => sort_order, + 'cursor' => cursor + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Charges a card represented by a card nonce or a customer's card on file. + # Deprecated - recommend using + # [CreatePayment](#endpoint-payments-createpayment) + # Your request to this endpoint must include _either_: + # - A value for the `card_nonce` parameter (to charge a card nonce generated + # with the `SqPaymentForm`) + # - Values for the `customer_card_id` and `customer_id` parameters (to + # charge + # a customer's card on file) + # When this response is returned, the amount of Square's processing fee + # might not yet be + # calculated. To obtain the processing fee, wait about ten seconds and call + # [RetrieveTransaction](#endpoint-transactions-retrievetransaction). See the + # `processing_fee_money` + # field of each [Tender included](#type-tender) in the transaction. + # @param [String] location_id Required parameter: The ID of the location to + # associate the created transaction with. + # @param [ChargeRequest] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [ChargeResponse Hash] response from the API call + def charge(location_id:, + body:) + warn 'Endpoint charge in TransactionsApi is deprecated' + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/transactions' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Retrieves details for a single transaction. + # Deprecated - recommend using + # [BatchRetrieveOrders](#endpoint-batchretrieveorders) + # @param [String] location_id Required parameter: The ID of the + # transaction's associated location. + # @param [String] transaction_id Required parameter: The ID of the + # transaction to retrieve. + # @return [RetrieveTransactionResponse Hash] response from the API call + def retrieve_transaction(location_id:, + transaction_id:) + warn 'Endpoint retrieve_transaction in TransactionsApi is deprecated' + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/transactions/{transaction_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'transaction_id' => transaction_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Captures a transaction that was created with the + # [Charge](#endpoint-transactions-charge) + # endpoint with a `delay_capture` value of `true`. + # See the [Delay Capture of + # Funds](https://developer.squareup.com/docs/transactions-api/cookbook/delay + # -capture) + # recipe for more information. + # @param [String] location_id Required parameter: Example: + # @param [String] transaction_id Required parameter: Example: + # @return [CaptureTransactionResponse Hash] response from the API call + def capture_transaction(location_id:, + transaction_id:) + warn 'Endpoint capture_transaction in TransactionsApi is deprecated' + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/transactions/{transaction_id}/capture' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'transaction_id' => transaction_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Initiates a refund for a previously charged tender. + # Deprecated - recommend using + # [RefundPayment](#endpoint-refunds-refundpayment) + # You must issue a refund within 120 days of the associated payment. See + # [this article](https://squareup.com/help/us/en/article/5060) for more + # information + # on refund behavior. + # NOTE: Card-present transactions with Interac credit cards **cannot be + # refunded using the Connect API**. Interac transactions must refunded + # in-person (e.g., dipping the card using POS app). + # @param [String] location_id Required parameter: The ID of the original + # transaction's associated location. + # @param [String] transaction_id Required parameter: The ID of the original + # transaction that includes the tender to refund. + # @param [CreateRefundRequest] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @return [CreateRefundResponse Hash] response from the API call + def create_refund(location_id:, + transaction_id:, + body:) + warn 'Endpoint create_refund in TransactionsApi is deprecated' + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/transactions/{transaction_id}/refund' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'transaction_id' => transaction_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Cancels a transaction that was created with the + # [Charge](#endpoint-transactions-charge) + # endpoint with a `delay_capture` value of `true`. + # See the [Delay Capture of + # Funds](https://developer.squareup.com/docs/transactions-api/cookbook/delay + # -capture) + # recipe for more information. + # @param [String] location_id Required parameter: Example: + # @param [String] transaction_id Required parameter: Example: + # @return [VoidTransactionResponse Hash] response from the API call + def void_transaction(location_id:, + transaction_id:) + warn 'Endpoint void_transaction in TransactionsApi is deprecated' + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v2/locations/{location_id}/transactions/{transaction_id}/void' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'transaction_id' => transaction_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/v1_employees_api.rb b/lib/square/api/v1_employees_api.rb index 1fe107e2..9ff5ad28 100644 --- a/lib/square/api/v1_employees_api.rb +++ b/lib/square/api/v1_employees_api.rb @@ -1,720 +1,720 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # V1EmployeesApi - class V1EmployeesApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Provides summary information for all of a business's employees. - # @param [SortOrder] order Optional parameter: The order in which employees - # are listed in the response, based on their created_at field. Default - # value: ASC - # @param [String] begin_updated_at Optional parameter: If filtering results - # by their updated_at field, the beginning of the requested reporting - # period, in ISO 8601 format - # @param [String] end_updated_at Optional parameter: If filtering results by - # there updated_at field, the end of the requested reporting period, in ISO - # 8601 format. - # @param [String] begin_created_at Optional parameter: If filtering results - # by their created_at field, the beginning of the requested reporting - # period, in ISO 8601 format. - # @param [String] end_created_at Optional parameter: If filtering results by - # their created_at field, the end of the requested reporting period, in ISO - # 8601 format. - # @param [V1EmployeeStatus] status Optional parameter: If provided, the - # endpoint returns only employee entities with the specified status (ACTIVE - # or INACTIVE). - # @param [String] external_id Optional parameter: If provided, the endpoint - # returns only employee entities with the specified external_id. - # @param [Integer] limit Optional parameter: The maximum integer number of - # employee entities to return in a single response. Default 100, maximum - # 200. - # @param [String] batch_token Optional parameter: A pagination cursor to - # retrieve the next set of results for your original query to the - # endpoint. - # @return [List of V1Employee Hash] response from the API call - def list_employees(order: nil, - begin_updated_at: nil, - end_updated_at: nil, - begin_created_at: nil, - end_created_at: nil, - status: nil, - external_id: nil, - limit: nil, - batch_token: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/employees' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'order' => order, - 'begin_updated_at' => begin_updated_at, - 'end_updated_at' => end_updated_at, - 'begin_created_at' => begin_created_at, - 'end_created_at' => end_created_at, - 'status' => status, - 'external_id' => external_id, - 'limit' => limit, - 'batch_token' => batch_token - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Use the CreateEmployee endpoint to add an employee to a Square - # account. Employees created with the Connect API have an initial status - # of `INACTIVE`. Inactive employees cannot sign in to Square Point of Sale - # until they are activated from the Square Dashboard. Employee status - # cannot be changed with the Connect API. - # - # @param [V1Employee] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Employee Hash] response from the API call - def create_employee(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/employees' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides the details for a single employee. - # @param [String] employee_id Required parameter: The employee's ID. - # @return [V1Employee Hash] response from the API call - def retrieve_employee(employee_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/employees/{employee_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'employee_id' => employee_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # UpdateEmployee - # @param [String] employee_id Required parameter: The ID of the role to - # modify. - # @param [V1Employee] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Employee Hash] response from the API call - def update_employee(employee_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/employees/{employee_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'employee_id' => employee_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides summary information for all of a business's employee roles. - # @param [SortOrder] order Optional parameter: The order in which employees - # are listed in the response, based on their created_at field.Default value: - # ASC - # @param [Integer] limit Optional parameter: The maximum integer number of - # employee entities to return in a single response. Default 100, maximum - # 200. - # @param [String] batch_token Optional parameter: A pagination cursor to - # retrieve the next set of results for your original query to the - # endpoint. - # @return [List of V1EmployeeRole Hash] response from the API call - def list_employee_roles(order: nil, - limit: nil, - batch_token: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/roles' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'order' => order, - 'limit' => limit, - 'batch_token' => batch_token - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates an employee role you can then assign to employees. - # Square accounts can include any number of roles that can be assigned to - # employees. These roles define the actions and permissions granted to an - # employee with that role. For example, an employee with a "Shift Manager" - # role might be able to issue refunds in Square Point of Sale, whereas an - # employee with a "Clerk" role might not. - # Roles are assigned with the [V1UpdateEmployee](#endpoint-v1updateemployee) - # endpoint. An employee can have only one role at a time. - # If an employee has no role, they have none of the permissions associated - # with roles. All employees can accept payments with Square Point of Sale. - # @param [V1EmployeeRole] body Required parameter: An EmployeeRole object - # with a name and permissions, and an optional owner flag. - # @return [V1EmployeeRole Hash] response from the API call - def create_employee_role(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/roles' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides the details for a single employee role. - # @param [String] role_id Required parameter: The role's ID. - # @return [V1EmployeeRole Hash] response from the API call - def retrieve_employee_role(role_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/roles/{role_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'role_id' => role_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies the details of an employee role. - # @param [String] role_id Required parameter: The ID of the role to - # modify. - # @param [V1EmployeeRole] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1EmployeeRole Hash] response from the API call - def update_employee_role(role_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/roles/{role_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'role_id' => role_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides summary information for all of a business's employee timecards. - # @param [SortOrder] order Optional parameter: The order in which timecards - # are listed in the response, based on their created_at field. - # @param [String] employee_id Optional parameter: If provided, the endpoint - # returns only timecards for the employee with the specified ID. - # @param [String] begin_clockin_time Optional parameter: If filtering - # results by their clockin_time field, the beginning of the requested - # reporting period, in ISO 8601 format. - # @param [String] end_clockin_time Optional parameter: If filtering results - # by their clockin_time field, the end of the requested reporting period, in - # ISO 8601 format. - # @param [String] begin_clockout_time Optional parameter: If filtering - # results by their clockout_time field, the beginning of the requested - # reporting period, in ISO 8601 format. - # @param [String] end_clockout_time Optional parameter: If filtering results - # by their clockout_time field, the end of the requested reporting period, - # in ISO 8601 format. - # @param [String] begin_updated_at Optional parameter: If filtering results - # by their updated_at field, the beginning of the requested reporting - # period, in ISO 8601 format. - # @param [String] end_updated_at Optional parameter: If filtering results by - # their updated_at field, the end of the requested reporting period, in ISO - # 8601 format. - # @param [Boolean] deleted Optional parameter: If true, only deleted - # timecards are returned. If false, only valid timecards are returned.If you - # don't provide this parameter, both valid and deleted timecards are - # returned. - # @param [Integer] limit Optional parameter: The maximum integer number of - # employee entities to return in a single response. Default 100, maximum - # 200. - # @param [String] batch_token Optional parameter: A pagination cursor to - # retrieve the next set of results for your original query to the - # endpoint. - # @return [List of V1Timecard Hash] response from the API call - def list_timecards(order: nil, - employee_id: nil, - begin_clockin_time: nil, - end_clockin_time: nil, - begin_clockout_time: nil, - end_clockout_time: nil, - begin_updated_at: nil, - end_updated_at: nil, - deleted: nil, - limit: nil, - batch_token: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/timecards' - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'order' => order, - 'employee_id' => employee_id, - 'begin_clockin_time' => begin_clockin_time, - 'end_clockin_time' => end_clockin_time, - 'begin_clockout_time' => begin_clockout_time, - 'end_clockout_time' => end_clockout_time, - 'begin_updated_at' => begin_updated_at, - 'end_updated_at' => end_updated_at, - 'deleted' => deleted, - 'limit' => limit, - 'batch_token' => batch_token - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates a timecard for an employee and clocks them in with an - # `API_CREATE` event and a `clockin_time` set to the current time unless - # the request provides a different value. To import timecards from another - # system (rather than clocking someone in). Specify the `clockin_time` - # and* `clockout_time` in the request. - # Timecards correspond to exactly one shift for a given employee, bounded - # by the `clockin_time` and `clockout_time` fields. An employee is - # considered clocked in if they have a timecard that doesn't have a - # `clockout_time` set. An employee that is currently clocked in cannot - # be clocked in a second time. - # @param [V1Timecard] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Timecard Hash] response from the API call - def create_timecard(body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/timecards' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes a timecard. Timecards can also be deleted through the - # Square Dashboard. Deleted timecards are still accessible through - # Connect API endpoints, but cannot be modified. The `deleted` field of - # the `Timecard` object indicates whether the timecard has been deleted. - # *Note**: By default, deleted timecards appear alongside valid timecards in - # results returned by the - # [ListTimecards](#endpoint-v1employees-listtimecards) - # endpoint. To filter deleted timecards, include the `deleted` query - # parameter in the list request. - # - # @param [String] timecard_id Required parameter: The ID of the timecard to - # delete. - # @return [Object] response from the API call - def delete_timecard(timecard_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/timecards/{timecard_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'timecard_id' => timecard_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - ApiResponse.new(_response, data: _response.raw_body) - end - - # Provides the details for a single timecard. - # - # @param [String] timecard_id Required parameter: The timecard's ID. - # @return [V1Timecard Hash] response from the API call - def retrieve_timecard(timecard_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/timecards/{timecard_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'timecard_id' => timecard_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies the details of a timecard with an `API_EDIT` event for - # the timecard. Updating an active timecard with a `clockout_time` - # clocks the employee out. - # @param [String] timecard_id Required parameter: TThe ID of the timecard to - # modify. - # @param [V1Timecard] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Timecard Hash] response from the API call - def update_timecard(timecard_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/timecards/{timecard_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'timecard_id' => timecard_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides summary information for all events associated with a - # particular timecard. - # - # @param [String] timecard_id Required parameter: The ID of the timecard to - # list events for. - # @return [List of V1TimecardEvent Hash] response from the API call - def list_timecard_events(timecard_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/timecards/{timecard_id}/events' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'timecard_id' => timecard_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides the details for all of a location's cash drawer shifts during a - # date range. The date range you specify cannot exceed 90 days. - # @param [String] location_id Required parameter: The ID of the location to - # list cash drawer shifts for. - # @param [SortOrder] order Optional parameter: The order in which cash - # drawer shifts are listed in the response, based on their created_at field. - # Default value: ASC - # @param [String] begin_time Optional parameter: The beginning of the - # requested reporting period, in ISO 8601 format. Default value: The current - # time minus 90 days. - # @param [String] end_time Optional parameter: The beginning of the - # requested reporting period, in ISO 8601 format. Default value: The current - # time. - # @return [List of V1CashDrawerShift Hash] response from the API call - def list_cash_drawer_shifts(location_id:, - order: nil, - begin_time: nil, - end_time: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/cash-drawer-shifts' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'order' => order, - 'begin_time' => begin_time, - 'end_time' => end_time - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides the details for a single cash drawer shift, including all events - # that occurred during the shift. - # @param [String] location_id Required parameter: The ID of the location to - # list cash drawer shifts for. - # @param [String] shift_id Required parameter: The shift's ID. - # @return [V1CashDrawerShift Hash] response from the API call - def retrieve_cash_drawer_shift(location_id:, - shift_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/cash-drawer-shifts/{shift_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'shift_id' => shift_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # V1EmployeesApi + class V1EmployeesApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Provides summary information for all of a business's employees. + # @param [SortOrder] order Optional parameter: The order in which employees + # are listed in the response, based on their created_at field. Default + # value: ASC + # @param [String] begin_updated_at Optional parameter: If filtering results + # by their updated_at field, the beginning of the requested reporting + # period, in ISO 8601 format + # @param [String] end_updated_at Optional parameter: If filtering results by + # there updated_at field, the end of the requested reporting period, in ISO + # 8601 format. + # @param [String] begin_created_at Optional parameter: If filtering results + # by their created_at field, the beginning of the requested reporting + # period, in ISO 8601 format. + # @param [String] end_created_at Optional parameter: If filtering results by + # their created_at field, the end of the requested reporting period, in ISO + # 8601 format. + # @param [V1EmployeeStatus] status Optional parameter: If provided, the + # endpoint returns only employee entities with the specified status (ACTIVE + # or INACTIVE). + # @param [String] external_id Optional parameter: If provided, the endpoint + # returns only employee entities with the specified external_id. + # @param [Integer] limit Optional parameter: The maximum integer number of + # employee entities to return in a single response. Default 100, maximum + # 200. + # @param [String] batch_token Optional parameter: A pagination cursor to + # retrieve the next set of results for your original query to the + # endpoint. + # @return [List of V1Employee Hash] response from the API call + def list_employees(order: nil, + begin_updated_at: nil, + end_updated_at: nil, + begin_created_at: nil, + end_created_at: nil, + status: nil, + external_id: nil, + limit: nil, + batch_token: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/employees' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'order' => order, + 'begin_updated_at' => begin_updated_at, + 'end_updated_at' => end_updated_at, + 'begin_created_at' => begin_created_at, + 'end_created_at' => end_created_at, + 'status' => status, + 'external_id' => external_id, + 'limit' => limit, + 'batch_token' => batch_token + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Use the CreateEmployee endpoint to add an employee to a Square + # account. Employees created with the Connect API have an initial status + # of `INACTIVE`. Inactive employees cannot sign in to Square Point of Sale + # until they are activated from the Square Dashboard. Employee status + # cannot be changed with the Connect API. + # + # @param [V1Employee] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Employee Hash] response from the API call + def create_employee(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/employees' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides the details for a single employee. + # @param [String] employee_id Required parameter: The employee's ID. + # @return [V1Employee Hash] response from the API call + def retrieve_employee(employee_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/employees/{employee_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'employee_id' => employee_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # UpdateEmployee + # @param [String] employee_id Required parameter: The ID of the role to + # modify. + # @param [V1Employee] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Employee Hash] response from the API call + def update_employee(employee_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/employees/{employee_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'employee_id' => employee_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides summary information for all of a business's employee roles. + # @param [SortOrder] order Optional parameter: The order in which employees + # are listed in the response, based on their created_at field.Default value: + # ASC + # @param [Integer] limit Optional parameter: The maximum integer number of + # employee entities to return in a single response. Default 100, maximum + # 200. + # @param [String] batch_token Optional parameter: A pagination cursor to + # retrieve the next set of results for your original query to the + # endpoint. + # @return [List of V1EmployeeRole Hash] response from the API call + def list_employee_roles(order: nil, + limit: nil, + batch_token: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/roles' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'order' => order, + 'limit' => limit, + 'batch_token' => batch_token + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates an employee role you can then assign to employees. + # Square accounts can include any number of roles that can be assigned to + # employees. These roles define the actions and permissions granted to an + # employee with that role. For example, an employee with a "Shift Manager" + # role might be able to issue refunds in Square Point of Sale, whereas an + # employee with a "Clerk" role might not. + # Roles are assigned with the [V1UpdateEmployee](#endpoint-v1updateemployee) + # endpoint. An employee can have only one role at a time. + # If an employee has no role, they have none of the permissions associated + # with roles. All employees can accept payments with Square Point of Sale. + # @param [V1EmployeeRole] body Required parameter: An EmployeeRole object + # with a name and permissions, and an optional owner flag. + # @return [V1EmployeeRole Hash] response from the API call + def create_employee_role(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/roles' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides the details for a single employee role. + # @param [String] role_id Required parameter: The role's ID. + # @return [V1EmployeeRole Hash] response from the API call + def retrieve_employee_role(role_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/roles/{role_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'role_id' => role_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies the details of an employee role. + # @param [String] role_id Required parameter: The ID of the role to + # modify. + # @param [V1EmployeeRole] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1EmployeeRole Hash] response from the API call + def update_employee_role(role_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/roles/{role_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'role_id' => role_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides summary information for all of a business's employee timecards. + # @param [SortOrder] order Optional parameter: The order in which timecards + # are listed in the response, based on their created_at field. + # @param [String] employee_id Optional parameter: If provided, the endpoint + # returns only timecards for the employee with the specified ID. + # @param [String] begin_clockin_time Optional parameter: If filtering + # results by their clockin_time field, the beginning of the requested + # reporting period, in ISO 8601 format. + # @param [String] end_clockin_time Optional parameter: If filtering results + # by their clockin_time field, the end of the requested reporting period, in + # ISO 8601 format. + # @param [String] begin_clockout_time Optional parameter: If filtering + # results by their clockout_time field, the beginning of the requested + # reporting period, in ISO 8601 format. + # @param [String] end_clockout_time Optional parameter: If filtering results + # by their clockout_time field, the end of the requested reporting period, + # in ISO 8601 format. + # @param [String] begin_updated_at Optional parameter: If filtering results + # by their updated_at field, the beginning of the requested reporting + # period, in ISO 8601 format. + # @param [String] end_updated_at Optional parameter: If filtering results by + # their updated_at field, the end of the requested reporting period, in ISO + # 8601 format. + # @param [Boolean] deleted Optional parameter: If true, only deleted + # timecards are returned. If false, only valid timecards are returned.If you + # don't provide this parameter, both valid and deleted timecards are + # returned. + # @param [Integer] limit Optional parameter: The maximum integer number of + # employee entities to return in a single response. Default 100, maximum + # 200. + # @param [String] batch_token Optional parameter: A pagination cursor to + # retrieve the next set of results for your original query to the + # endpoint. + # @return [List of V1Timecard Hash] response from the API call + def list_timecards(order: nil, + employee_id: nil, + begin_clockin_time: nil, + end_clockin_time: nil, + begin_clockout_time: nil, + end_clockout_time: nil, + begin_updated_at: nil, + end_updated_at: nil, + deleted: nil, + limit: nil, + batch_token: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/timecards' + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'order' => order, + 'employee_id' => employee_id, + 'begin_clockin_time' => begin_clockin_time, + 'end_clockin_time' => end_clockin_time, + 'begin_clockout_time' => begin_clockout_time, + 'end_clockout_time' => end_clockout_time, + 'begin_updated_at' => begin_updated_at, + 'end_updated_at' => end_updated_at, + 'deleted' => deleted, + 'limit' => limit, + 'batch_token' => batch_token + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates a timecard for an employee and clocks them in with an + # `API_CREATE` event and a `clockin_time` set to the current time unless + # the request provides a different value. To import timecards from another + # system (rather than clocking someone in). Specify the `clockin_time` + # and* `clockout_time` in the request. + # Timecards correspond to exactly one shift for a given employee, bounded + # by the `clockin_time` and `clockout_time` fields. An employee is + # considered clocked in if they have a timecard that doesn't have a + # `clockout_time` set. An employee that is currently clocked in cannot + # be clocked in a second time. + # @param [V1Timecard] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Timecard Hash] response from the API call + def create_timecard(body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/timecards' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes a timecard. Timecards can also be deleted through the + # Square Dashboard. Deleted timecards are still accessible through + # Connect API endpoints, but cannot be modified. The `deleted` field of + # the `Timecard` object indicates whether the timecard has been deleted. + # *Note**: By default, deleted timecards appear alongside valid timecards in + # results returned by the + # [ListTimecards](#endpoint-v1employees-listtimecards) + # endpoint. To filter deleted timecards, include the `deleted` query + # parameter in the list request. + # + # @param [String] timecard_id Required parameter: The ID of the timecard to + # delete. + # @return [Object] response from the API call + def delete_timecard(timecard_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/timecards/{timecard_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'timecard_id' => timecard_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + ApiResponse.new(_response, data: _response.raw_body) + end + + # Provides the details for a single timecard. + # + # @param [String] timecard_id Required parameter: The timecard's ID. + # @return [V1Timecard Hash] response from the API call + def retrieve_timecard(timecard_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/timecards/{timecard_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'timecard_id' => timecard_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies the details of a timecard with an `API_EDIT` event for + # the timecard. Updating an active timecard with a `clockout_time` + # clocks the employee out. + # @param [String] timecard_id Required parameter: TThe ID of the timecard to + # modify. + # @param [V1Timecard] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Timecard Hash] response from the API call + def update_timecard(timecard_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/timecards/{timecard_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'timecard_id' => timecard_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides summary information for all events associated with a + # particular timecard. + # + # @param [String] timecard_id Required parameter: The ID of the timecard to + # list events for. + # @return [List of V1TimecardEvent Hash] response from the API call + def list_timecard_events(timecard_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/timecards/{timecard_id}/events' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'timecard_id' => timecard_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides the details for all of a location's cash drawer shifts during a + # date range. The date range you specify cannot exceed 90 days. + # @param [String] location_id Required parameter: The ID of the location to + # list cash drawer shifts for. + # @param [SortOrder] order Optional parameter: The order in which cash + # drawer shifts are listed in the response, based on their created_at field. + # Default value: ASC + # @param [String] begin_time Optional parameter: The beginning of the + # requested reporting period, in ISO 8601 format. Default value: The current + # time minus 90 days. + # @param [String] end_time Optional parameter: The beginning of the + # requested reporting period, in ISO 8601 format. Default value: The current + # time. + # @return [List of V1CashDrawerShift Hash] response from the API call + def list_cash_drawer_shifts(location_id:, + order: nil, + begin_time: nil, + end_time: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/cash-drawer-shifts' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'order' => order, + 'begin_time' => begin_time, + 'end_time' => end_time + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides the details for a single cash drawer shift, including all events + # that occurred during the shift. + # @param [String] location_id Required parameter: The ID of the location to + # list cash drawer shifts for. + # @param [String] shift_id Required parameter: The shift's ID. + # @return [V1CashDrawerShift Hash] response from the API call + def retrieve_cash_drawer_shift(location_id:, + shift_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/cash-drawer-shifts/{shift_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'shift_id' => shift_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/v1_items_api.rb b/lib/square/api/v1_items_api.rb index 7c7ecaa7..7d25c3d8 100644 --- a/lib/square/api/v1_items_api.rb +++ b/lib/square/api/v1_items_api.rb @@ -1,1651 +1,1651 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # V1ItemsApi - class V1ItemsApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Lists all of a location's item categories. - # @param [String] location_id Required parameter: The ID of the location to - # list categories for. - # @return [List of V1Category Hash] response from the API call - def list_categories(location_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/categories' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates an item category. - # @param [String] location_id Required parameter: The ID of the location to - # create an item for. - # @param [V1Category] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Category Hash] response from the API call - def create_category(location_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/categories' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes an existing item category. - # *Note**: DeleteCategory returns nothing on success but Connect SDKs - # map the empty response to an empty `V1DeleteCategoryRequest` object - # as documented below. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] category_id Required parameter: The ID of the category to - # delete. - # @return [V1Category Hash] response from the API call - def delete_category(location_id:, - category_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/categories/{category_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'category_id' => category_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies the details of an existing item category. - # @param [String] location_id Required parameter: The ID of the category's - # associated location. - # @param [String] category_id Required parameter: The ID of the category to - # edit. - # @param [V1Category] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Category Hash] response from the API call - def update_category(location_id:, - category_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/categories/{category_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'category_id' => category_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Lists all of a location's discounts. - # @param [String] location_id Required parameter: The ID of the location to - # list categories for. - # @return [List of V1Discount Hash] response from the API call - def list_discounts(location_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/discounts' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates a discount. - # @param [String] location_id Required parameter: The ID of the location to - # create an item for. - # @param [V1Discount] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Discount Hash] response from the API call - def create_discount(location_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/discounts' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes an existing discount. - # *Note**: DeleteDiscount returns nothing on success but Connect SDKs - # map the empty response to an empty `V1DeleteDiscountRequest` object - # as documented below. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] discount_id Required parameter: The ID of the discount to - # delete. - # @return [V1Discount Hash] response from the API call - def delete_discount(location_id:, - discount_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/discounts/{discount_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'discount_id' => discount_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies the details of an existing discount. - # @param [String] location_id Required parameter: The ID of the category's - # associated location. - # @param [String] discount_id Required parameter: The ID of the discount to - # edit. - # @param [V1Discount] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Discount Hash] response from the API call - def update_discount(location_id:, - discount_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/discounts/{discount_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'discount_id' => discount_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Lists all of a location's fees (taxes). - # @param [String] location_id Required parameter: The ID of the location to - # list fees for. - # @return [List of V1Fee Hash] response from the API call - def list_fees(location_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/fees' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates a fee (tax). - # @param [String] location_id Required parameter: The ID of the location to - # create a fee for. - # @param [V1Fee] body Required parameter: An object containing the fields to - # POST for the request. See the corresponding object definition for field - # details. - # @return [V1Fee Hash] response from the API call - def create_fee(location_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/fees' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes an existing fee (tax). - # *Note**: DeleteFee returns nothing on success but Connect SDKs - # map the empty response to an empty `V1DeleteFeeRequest` object - # as documented below. - # @param [String] location_id Required parameter: The ID of the fee's - # associated location. - # @param [String] fee_id Required parameter: The ID of the fee to delete. - # @return [V1Fee Hash] response from the API call - def delete_fee(location_id:, - fee_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/fees/{fee_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'fee_id' => fee_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies the details of an existing fee (tax). - # @param [String] location_id Required parameter: The ID of the fee's - # associated location. - # @param [String] fee_id Required parameter: The ID of the fee to edit. - # @param [V1Fee] body Required parameter: An object containing the fields to - # POST for the request. See the corresponding object definition for field - # details. - # @return [V1Fee Hash] response from the API call - def update_fee(location_id:, - fee_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/fees/{fee_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'fee_id' => fee_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides inventory information for all of a merchant's inventory-enabled - # item variations. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [Integer] limit Optional parameter: The maximum number of inventory - # entries to return in a single response. This value cannot exceed 1000. - # @param [String] batch_token Optional parameter: A pagination cursor to - # retrieve the next set of results for your original query to the - # endpoint. - # @return [List of V1InventoryEntry Hash] response from the API call - def list_inventory(location_id:, - limit: nil, - batch_token: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/inventory' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'limit' => limit, - 'batch_token' => batch_token - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Adjusts an item variation's current available inventory. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] variation_id Required parameter: The ID of the variation - # to adjust inventory information for. - # @param [V1AdjustInventoryRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [V1InventoryEntry Hash] response from the API call - def adjust_inventory(location_id:, - variation_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/inventory/{variation_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'variation_id' => variation_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides summary information for all of a location's items. - # @param [String] location_id Required parameter: The ID of the location to - # list items for. - # @param [String] batch_token Optional parameter: A pagination cursor to - # retrieve the next set of results for your original query to the - # endpoint. - # @return [List of V1Item Hash] response from the API call - def list_items(location_id:, - batch_token: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'batch_token' => batch_token - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates an item and at least one variation for it. Item-related - # entities include fields you can use to associate them with entities in a - # non-Square system. - # When you create an item-related entity, you can optionally specify its - # `id`. This value must be unique among all IDs ever specified for the - # account, including those specified by other applications. You can never - # reuse an entity ID. If you do not specify an ID, Square generates one - # for the entity. - # Item variations have a `user_data` string that lets you associate - # arbitrary metadata with the variation. The string cannot exceed 255 - # characters. - # @param [String] location_id Required parameter: The ID of the location to - # create an item for. - # @param [V1Item] body Required parameter: An object containing the fields - # to POST for the request. See the corresponding object definition for - # field details. - # @return [V1Item Hash] response from the API call - def create_item(location_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes an existing item and all item variations associated with it. - # *Note**: DeleteItem returns nothing on success but Connect SDKs - # map the empty response to an empty `V1DeleteItemRequest` object - # as documented below. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] item_id Required parameter: The ID of the item to - # modify. - # @return [V1Item Hash] response from the API call - def delete_item(location_id:, - item_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items/{item_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'item_id' => item_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides the details for a single item, including associated modifier - # lists and fees. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] item_id Required parameter: The item's ID. - # @return [V1Item Hash] response from the API call - def retrieve_item(location_id:, - item_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items/{item_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'item_id' => item_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies the core details of an existing item. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] item_id Required parameter: The ID of the item to - # modify. - # @param [V1Item] body Required parameter: An object containing the fields - # to POST for the request. See the corresponding object definition for - # field details. - # @return [V1Item Hash] response from the API call - def update_item(location_id:, - item_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items/{item_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'item_id' => item_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Removes a fee assocation from an item, meaning the fee is no longer - # automatically applied to the item in Square Register. - # @param [String] location_id Required parameter: The ID of the fee's - # associated location. - # @param [String] item_id Required parameter: The ID of the item to add the - # fee to. - # @param [String] fee_id Required parameter: The ID of the fee to apply. - # @return [V1Item Hash] response from the API call - def remove_fee(location_id:, - item_id:, - fee_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items/{item_id}/fees/{fee_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'item_id' => item_id, - 'fee_id' => fee_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Associates a fee with an item, meaning the fee is automatically applied to - # the item in Square Register. - # @param [String] location_id Required parameter: The ID of the fee's - # associated location. - # @param [String] item_id Required parameter: The ID of the item to add the - # fee to. - # @param [String] fee_id Required parameter: The ID of the fee to apply. - # @return [V1Item Hash] response from the API call - def apply_fee(location_id:, - item_id:, - fee_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items/{item_id}/fees/{fee_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'item_id' => item_id, - 'fee_id' => fee_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Removes a modifier list association from an item, meaning modifier options - # from the list can no longer be applied to the item. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] modifier_list_id Required parameter: The ID of the - # modifier list to remove. - # @param [String] item_id Required parameter: The ID of the item to remove - # the modifier list from. - # @return [V1Item Hash] response from the API call - def remove_modifier_list(location_id:, - modifier_list_id:, - item_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'modifier_list_id' => modifier_list_id, - 'item_id' => item_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Associates a modifier list with an item, meaning modifier options from the - # list can be applied to the item. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] modifier_list_id Required parameter: The ID of the - # modifier list to apply. - # @param [String] item_id Required parameter: The ID of the item to add the - # modifier list to. - # @return [V1Item Hash] response from the API call - def apply_modifier_list(location_id:, - modifier_list_id:, - item_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'modifier_list_id' => modifier_list_id, - 'item_id' => item_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates an item variation for an existing item. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] item_id Required parameter: The item's ID. - # @param [V1Variation] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Variation Hash] response from the API call - def create_variation(location_id:, - item_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items/{item_id}/variations' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'item_id' => item_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes an existing item variation from an item. - # *Note**: DeleteVariation returns nothing on success but Connect SDKs - # map the empty response to an empty `V1DeleteVariationRequest` object - # as documented below. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] item_id Required parameter: The ID of the item to - # delete. - # @param [String] variation_id Required parameter: The ID of the variation - # to delete. - # @return [V1Variation Hash] response from the API call - def delete_variation(location_id:, - item_id:, - variation_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items/{item_id}/variations/{variation_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'item_id' => item_id, - 'variation_id' => variation_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies the details of an existing item variation. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] item_id Required parameter: The ID of the item to - # modify. - # @param [String] variation_id Required parameter: The ID of the variation - # to modify. - # @param [V1Variation] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Variation Hash] response from the API call - def update_variation(location_id:, - item_id:, - variation_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/items/{item_id}/variations/{variation_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'item_id' => item_id, - 'variation_id' => variation_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Lists all of a location's modifier lists. - # @param [String] location_id Required parameter: The ID of the location to - # list modifier lists for. - # @return [List of V1ModifierList Hash] response from the API call - def list_modifier_lists(location_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/modifier-lists' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates an item modifier list and at least one modifier option for it. - # @param [String] location_id Required parameter: The ID of the location to - # create a modifier list for. - # @param [V1ModifierList] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1ModifierList Hash] response from the API call - def create_modifier_list(location_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/modifier-lists' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes an existing item modifier list and all modifier options - # associated with it. - # *Note**: DeleteModifierList returns nothing on success but Connect SDKs - # map the empty response to an empty `V1DeleteModifierListRequest` object - # as documented below. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] modifier_list_id Required parameter: The ID of the - # modifier list to delete. - # @return [V1ModifierList Hash] response from the API call - def delete_modifier_list(location_id:, - modifier_list_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'modifier_list_id' => modifier_list_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides the details for a single modifier list. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] modifier_list_id Required parameter: The modifier list's - # ID. - # @return [V1ModifierList Hash] response from the API call - def retrieve_modifier_list(location_id:, - modifier_list_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'modifier_list_id' => modifier_list_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies the details of an existing item modifier list. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] modifier_list_id Required parameter: The ID of the - # modifier list to edit. - # @param [V1UpdateModifierListRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [V1ModifierList Hash] response from the API call - def update_modifier_list(location_id:, - modifier_list_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'modifier_list_id' => modifier_list_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates an item modifier option and adds it to a modifier list. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] modifier_list_id Required parameter: The ID of the - # modifier list to edit. - # @param [V1ModifierOption] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @return [V1ModifierOption Hash] response from the API call - def create_modifier_option(location_id:, - modifier_list_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'modifier_list_id' => modifier_list_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes an existing item modifier option from a modifier list. - # *Note**: DeleteModifierOption returns nothing on success but Connect SDKs - # map the empty response to an empty `V1DeleteModifierOptionRequest` object - # as documented below. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] modifier_list_id Required parameter: The ID of the - # modifier list to delete. - # @param [String] modifier_option_id Required parameter: The ID of the - # modifier list to edit. - # @return [V1ModifierOption Hash] response from the API call - def delete_modifier_option(location_id:, - modifier_list_id:, - modifier_option_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'modifier_list_id' => modifier_list_id, - 'modifier_option_id' => modifier_option_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies the details of an existing item modifier option. - # @param [String] location_id Required parameter: The ID of the item's - # associated location. - # @param [String] modifier_list_id Required parameter: The ID of the - # modifier list to edit. - # @param [String] modifier_option_id Required parameter: The ID of the - # modifier list to edit. - # @param [V1ModifierOption] body Required parameter: An object containing - # the fields to POST for the request. See the corresponding object - # definition for field details. - # @return [V1ModifierOption Hash] response from the API call - def update_modifier_option(location_id:, - modifier_list_id:, - modifier_option_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'modifier_list_id' => modifier_list_id, - 'modifier_option_id' => modifier_option_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Lists all of a location's Favorites pages in Square Register. - # @param [String] location_id Required parameter: The ID of the location to - # list Favorites pages for. - # @return [List of V1Page Hash] response from the API call - def list_pages(location_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/pages' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Creates a Favorites page in Square Register. - # @param [String] location_id Required parameter: The ID of the location to - # create an item for. - # @param [V1Page] body Required parameter: An object containing the fields - # to POST for the request. See the corresponding object definition for - # field details. - # @return [V1Page Hash] response from the API call - def create_page(location_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/pages' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes an existing Favorites page and all of its cells. - # *Note**: DeletePage returns nothing on success but Connect SDKs - # map the empty response to an empty `V1DeletePageRequest` object - # as documented below. - # @param [String] location_id Required parameter: The ID of the Favorites - # page's associated location. - # @param [String] page_id Required parameter: The ID of the page to - # delete. - # @return [V1Page Hash] response from the API call - def delete_page(location_id:, - page_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/pages/{page_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'page_id' => page_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies the details of a Favorites page in Square Register. - # @param [String] location_id Required parameter: The ID of the Favorites - # page's associated location - # @param [String] page_id Required parameter: The ID of the page to - # modify. - # @param [V1Page] body Required parameter: An object containing the fields - # to POST for the request. See the corresponding object definition for - # field details. - # @return [V1Page Hash] response from the API call - def update_page(location_id:, - page_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/pages/{page_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'page_id' => page_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Deletes a cell from a Favorites page in Square Register. - # *Note**: DeletePageCell returns nothing on success but Connect SDKs - # map the empty response to an empty `V1DeletePageCellRequest` object - # as documented below. - # @param [String] location_id Required parameter: The ID of the Favorites - # page's associated location. - # @param [String] page_id Required parameter: The ID of the page to - # delete. - # @param [String] row Optional parameter: The row of the cell to clear. - # Always an integer between 0 and 4, inclusive. Row 0 is the top row. - # @param [String] column Optional parameter: The column of the cell to - # clear. Always an integer between 0 and 4, inclusive. Column 0 is the - # leftmost column. - # @return [V1Page Hash] response from the API call - def delete_page_cell(location_id:, - page_id:, - row: nil, - column: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/pages/{page_id}/cells' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'page_id' => page_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'row' => row, - 'column' => column - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.delete( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Modifies a cell of a Favorites page in Square Register. - # @param [String] location_id Required parameter: The ID of the Favorites - # page's associated location. - # @param [String] page_id Required parameter: The ID of the page the cell - # belongs to. - # @param [V1PageCell] body Required parameter: An object containing the - # fields to POST for the request. See the corresponding object definition - # for field details. - # @return [V1Page Hash] response from the API call - def update_page_cell(location_id:, - page_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/pages/{page_id}/cells' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'page_id' => page_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # V1ItemsApi + class V1ItemsApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Lists all of a location's item categories. + # @param [String] location_id Required parameter: The ID of the location to + # list categories for. + # @return [List of V1Category Hash] response from the API call + def list_categories(location_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/categories' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates an item category. + # @param [String] location_id Required parameter: The ID of the location to + # create an item for. + # @param [V1Category] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Category Hash] response from the API call + def create_category(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/categories' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes an existing item category. + # *Note**: DeleteCategory returns nothing on success but Connect SDKs + # map the empty response to an empty `V1DeleteCategoryRequest` object + # as documented below. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] category_id Required parameter: The ID of the category to + # delete. + # @return [V1Category Hash] response from the API call + def delete_category(location_id:, + category_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/categories/{category_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'category_id' => category_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies the details of an existing item category. + # @param [String] location_id Required parameter: The ID of the category's + # associated location. + # @param [String] category_id Required parameter: The ID of the category to + # edit. + # @param [V1Category] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Category Hash] response from the API call + def update_category(location_id:, + category_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/categories/{category_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'category_id' => category_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Lists all of a location's discounts. + # @param [String] location_id Required parameter: The ID of the location to + # list categories for. + # @return [List of V1Discount Hash] response from the API call + def list_discounts(location_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/discounts' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates a discount. + # @param [String] location_id Required parameter: The ID of the location to + # create an item for. + # @param [V1Discount] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Discount Hash] response from the API call + def create_discount(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/discounts' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes an existing discount. + # *Note**: DeleteDiscount returns nothing on success but Connect SDKs + # map the empty response to an empty `V1DeleteDiscountRequest` object + # as documented below. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] discount_id Required parameter: The ID of the discount to + # delete. + # @return [V1Discount Hash] response from the API call + def delete_discount(location_id:, + discount_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/discounts/{discount_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'discount_id' => discount_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies the details of an existing discount. + # @param [String] location_id Required parameter: The ID of the category's + # associated location. + # @param [String] discount_id Required parameter: The ID of the discount to + # edit. + # @param [V1Discount] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Discount Hash] response from the API call + def update_discount(location_id:, + discount_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/discounts/{discount_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'discount_id' => discount_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Lists all of a location's fees (taxes). + # @param [String] location_id Required parameter: The ID of the location to + # list fees for. + # @return [List of V1Fee Hash] response from the API call + def list_fees(location_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/fees' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates a fee (tax). + # @param [String] location_id Required parameter: The ID of the location to + # create a fee for. + # @param [V1Fee] body Required parameter: An object containing the fields to + # POST for the request. See the corresponding object definition for field + # details. + # @return [V1Fee Hash] response from the API call + def create_fee(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/fees' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes an existing fee (tax). + # *Note**: DeleteFee returns nothing on success but Connect SDKs + # map the empty response to an empty `V1DeleteFeeRequest` object + # as documented below. + # @param [String] location_id Required parameter: The ID of the fee's + # associated location. + # @param [String] fee_id Required parameter: The ID of the fee to delete. + # @return [V1Fee Hash] response from the API call + def delete_fee(location_id:, + fee_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/fees/{fee_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'fee_id' => fee_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies the details of an existing fee (tax). + # @param [String] location_id Required parameter: The ID of the fee's + # associated location. + # @param [String] fee_id Required parameter: The ID of the fee to edit. + # @param [V1Fee] body Required parameter: An object containing the fields to + # POST for the request. See the corresponding object definition for field + # details. + # @return [V1Fee Hash] response from the API call + def update_fee(location_id:, + fee_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/fees/{fee_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'fee_id' => fee_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides inventory information for all of a merchant's inventory-enabled + # item variations. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [Integer] limit Optional parameter: The maximum number of inventory + # entries to return in a single response. This value cannot exceed 1000. + # @param [String] batch_token Optional parameter: A pagination cursor to + # retrieve the next set of results for your original query to the + # endpoint. + # @return [List of V1InventoryEntry Hash] response from the API call + def list_inventory(location_id:, + limit: nil, + batch_token: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/inventory' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'limit' => limit, + 'batch_token' => batch_token + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Adjusts an item variation's current available inventory. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] variation_id Required parameter: The ID of the variation + # to adjust inventory information for. + # @param [V1AdjustInventoryRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [V1InventoryEntry Hash] response from the API call + def adjust_inventory(location_id:, + variation_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/inventory/{variation_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'variation_id' => variation_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides summary information for all of a location's items. + # @param [String] location_id Required parameter: The ID of the location to + # list items for. + # @param [String] batch_token Optional parameter: A pagination cursor to + # retrieve the next set of results for your original query to the + # endpoint. + # @return [List of V1Item Hash] response from the API call + def list_items(location_id:, + batch_token: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'batch_token' => batch_token + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates an item and at least one variation for it. Item-related + # entities include fields you can use to associate them with entities in a + # non-Square system. + # When you create an item-related entity, you can optionally specify its + # `id`. This value must be unique among all IDs ever specified for the + # account, including those specified by other applications. You can never + # reuse an entity ID. If you do not specify an ID, Square generates one + # for the entity. + # Item variations have a `user_data` string that lets you associate + # arbitrary metadata with the variation. The string cannot exceed 255 + # characters. + # @param [String] location_id Required parameter: The ID of the location to + # create an item for. + # @param [V1Item] body Required parameter: An object containing the fields + # to POST for the request. See the corresponding object definition for + # field details. + # @return [V1Item Hash] response from the API call + def create_item(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes an existing item and all item variations associated with it. + # *Note**: DeleteItem returns nothing on success but Connect SDKs + # map the empty response to an empty `V1DeleteItemRequest` object + # as documented below. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] item_id Required parameter: The ID of the item to + # modify. + # @return [V1Item Hash] response from the API call + def delete_item(location_id:, + item_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items/{item_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'item_id' => item_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides the details for a single item, including associated modifier + # lists and fees. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] item_id Required parameter: The item's ID. + # @return [V1Item Hash] response from the API call + def retrieve_item(location_id:, + item_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items/{item_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'item_id' => item_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies the core details of an existing item. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] item_id Required parameter: The ID of the item to + # modify. + # @param [V1Item] body Required parameter: An object containing the fields + # to POST for the request. See the corresponding object definition for + # field details. + # @return [V1Item Hash] response from the API call + def update_item(location_id:, + item_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items/{item_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'item_id' => item_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Removes a fee assocation from an item, meaning the fee is no longer + # automatically applied to the item in Square Register. + # @param [String] location_id Required parameter: The ID of the fee's + # associated location. + # @param [String] item_id Required parameter: The ID of the item to add the + # fee to. + # @param [String] fee_id Required parameter: The ID of the fee to apply. + # @return [V1Item Hash] response from the API call + def remove_fee(location_id:, + item_id:, + fee_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items/{item_id}/fees/{fee_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'item_id' => item_id, + 'fee_id' => fee_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Associates a fee with an item, meaning the fee is automatically applied to + # the item in Square Register. + # @param [String] location_id Required parameter: The ID of the fee's + # associated location. + # @param [String] item_id Required parameter: The ID of the item to add the + # fee to. + # @param [String] fee_id Required parameter: The ID of the fee to apply. + # @return [V1Item Hash] response from the API call + def apply_fee(location_id:, + item_id:, + fee_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items/{item_id}/fees/{fee_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'item_id' => item_id, + 'fee_id' => fee_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Removes a modifier list association from an item, meaning modifier options + # from the list can no longer be applied to the item. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] modifier_list_id Required parameter: The ID of the + # modifier list to remove. + # @param [String] item_id Required parameter: The ID of the item to remove + # the modifier list from. + # @return [V1Item Hash] response from the API call + def remove_modifier_list(location_id:, + modifier_list_id:, + item_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'modifier_list_id' => modifier_list_id, + 'item_id' => item_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Associates a modifier list with an item, meaning modifier options from the + # list can be applied to the item. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] modifier_list_id Required parameter: The ID of the + # modifier list to apply. + # @param [String] item_id Required parameter: The ID of the item to add the + # modifier list to. + # @return [V1Item Hash] response from the API call + def apply_modifier_list(location_id:, + modifier_list_id:, + item_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'modifier_list_id' => modifier_list_id, + 'item_id' => item_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates an item variation for an existing item. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] item_id Required parameter: The item's ID. + # @param [V1Variation] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Variation Hash] response from the API call + def create_variation(location_id:, + item_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items/{item_id}/variations' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'item_id' => item_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes an existing item variation from an item. + # *Note**: DeleteVariation returns nothing on success but Connect SDKs + # map the empty response to an empty `V1DeleteVariationRequest` object + # as documented below. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] item_id Required parameter: The ID of the item to + # delete. + # @param [String] variation_id Required parameter: The ID of the variation + # to delete. + # @return [V1Variation Hash] response from the API call + def delete_variation(location_id:, + item_id:, + variation_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items/{item_id}/variations/{variation_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'item_id' => item_id, + 'variation_id' => variation_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies the details of an existing item variation. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] item_id Required parameter: The ID of the item to + # modify. + # @param [String] variation_id Required parameter: The ID of the variation + # to modify. + # @param [V1Variation] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Variation Hash] response from the API call + def update_variation(location_id:, + item_id:, + variation_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/items/{item_id}/variations/{variation_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'item_id' => item_id, + 'variation_id' => variation_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Lists all of a location's modifier lists. + # @param [String] location_id Required parameter: The ID of the location to + # list modifier lists for. + # @return [List of V1ModifierList Hash] response from the API call + def list_modifier_lists(location_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/modifier-lists' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates an item modifier list and at least one modifier option for it. + # @param [String] location_id Required parameter: The ID of the location to + # create a modifier list for. + # @param [V1ModifierList] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1ModifierList Hash] response from the API call + def create_modifier_list(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/modifier-lists' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes an existing item modifier list and all modifier options + # associated with it. + # *Note**: DeleteModifierList returns nothing on success but Connect SDKs + # map the empty response to an empty `V1DeleteModifierListRequest` object + # as documented below. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] modifier_list_id Required parameter: The ID of the + # modifier list to delete. + # @return [V1ModifierList Hash] response from the API call + def delete_modifier_list(location_id:, + modifier_list_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'modifier_list_id' => modifier_list_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides the details for a single modifier list. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] modifier_list_id Required parameter: The modifier list's + # ID. + # @return [V1ModifierList Hash] response from the API call + def retrieve_modifier_list(location_id:, + modifier_list_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'modifier_list_id' => modifier_list_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies the details of an existing item modifier list. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] modifier_list_id Required parameter: The ID of the + # modifier list to edit. + # @param [V1UpdateModifierListRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [V1ModifierList Hash] response from the API call + def update_modifier_list(location_id:, + modifier_list_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'modifier_list_id' => modifier_list_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates an item modifier option and adds it to a modifier list. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] modifier_list_id Required parameter: The ID of the + # modifier list to edit. + # @param [V1ModifierOption] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @return [V1ModifierOption Hash] response from the API call + def create_modifier_option(location_id:, + modifier_list_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'modifier_list_id' => modifier_list_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes an existing item modifier option from a modifier list. + # *Note**: DeleteModifierOption returns nothing on success but Connect SDKs + # map the empty response to an empty `V1DeleteModifierOptionRequest` object + # as documented below. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] modifier_list_id Required parameter: The ID of the + # modifier list to delete. + # @param [String] modifier_option_id Required parameter: The ID of the + # modifier list to edit. + # @return [V1ModifierOption Hash] response from the API call + def delete_modifier_option(location_id:, + modifier_list_id:, + modifier_option_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'modifier_list_id' => modifier_list_id, + 'modifier_option_id' => modifier_option_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies the details of an existing item modifier option. + # @param [String] location_id Required parameter: The ID of the item's + # associated location. + # @param [String] modifier_list_id Required parameter: The ID of the + # modifier list to edit. + # @param [String] modifier_option_id Required parameter: The ID of the + # modifier list to edit. + # @param [V1ModifierOption] body Required parameter: An object containing + # the fields to POST for the request. See the corresponding object + # definition for field details. + # @return [V1ModifierOption Hash] response from the API call + def update_modifier_option(location_id:, + modifier_list_id:, + modifier_option_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'modifier_list_id' => modifier_list_id, + 'modifier_option_id' => modifier_option_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Lists all of a location's Favorites pages in Square Register. + # @param [String] location_id Required parameter: The ID of the location to + # list Favorites pages for. + # @return [List of V1Page Hash] response from the API call + def list_pages(location_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/pages' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Creates a Favorites page in Square Register. + # @param [String] location_id Required parameter: The ID of the location to + # create an item for. + # @param [V1Page] body Required parameter: An object containing the fields + # to POST for the request. See the corresponding object definition for + # field details. + # @return [V1Page Hash] response from the API call + def create_page(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/pages' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes an existing Favorites page and all of its cells. + # *Note**: DeletePage returns nothing on success but Connect SDKs + # map the empty response to an empty `V1DeletePageRequest` object + # as documented below. + # @param [String] location_id Required parameter: The ID of the Favorites + # page's associated location. + # @param [String] page_id Required parameter: The ID of the page to + # delete. + # @return [V1Page Hash] response from the API call + def delete_page(location_id:, + page_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/pages/{page_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'page_id' => page_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies the details of a Favorites page in Square Register. + # @param [String] location_id Required parameter: The ID of the Favorites + # page's associated location + # @param [String] page_id Required parameter: The ID of the page to + # modify. + # @param [V1Page] body Required parameter: An object containing the fields + # to POST for the request. See the corresponding object definition for + # field details. + # @return [V1Page Hash] response from the API call + def update_page(location_id:, + page_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/pages/{page_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'page_id' => page_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Deletes a cell from a Favorites page in Square Register. + # *Note**: DeletePageCell returns nothing on success but Connect SDKs + # map the empty response to an empty `V1DeletePageCellRequest` object + # as documented below. + # @param [String] location_id Required parameter: The ID of the Favorites + # page's associated location. + # @param [String] page_id Required parameter: The ID of the page to + # delete. + # @param [String] row Optional parameter: The row of the cell to clear. + # Always an integer between 0 and 4, inclusive. Row 0 is the top row. + # @param [String] column Optional parameter: The column of the cell to + # clear. Always an integer between 0 and 4, inclusive. Column 0 is the + # leftmost column. + # @return [V1Page Hash] response from the API call + def delete_page_cell(location_id:, + page_id:, + row: nil, + column: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/pages/{page_id}/cells' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'page_id' => page_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'row' => row, + 'column' => column + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.delete( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Modifies a cell of a Favorites page in Square Register. + # @param [String] location_id Required parameter: The ID of the Favorites + # page's associated location. + # @param [String] page_id Required parameter: The ID of the page the cell + # belongs to. + # @param [V1PageCell] body Required parameter: An object containing the + # fields to POST for the request. See the corresponding object definition + # for field details. + # @return [V1Page Hash] response from the API call + def update_page_cell(location_id:, + page_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/pages/{page_id}/cells' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'page_id' => page_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/v1_locations_api.rb b/lib/square/api/v1_locations_api.rb index 125c8544..60503f55 100644 --- a/lib/square/api/v1_locations_api.rb +++ b/lib/square/api/v1_locations_api.rb @@ -1,67 +1,67 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # V1LocationsApi - class V1LocationsApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Get a business's information. - # @return [V1Merchant Hash] response from the API call - def retrieve_business - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides details for a business's locations, including their IDs. - # @return [List of V1Merchant Hash] response from the API call - def list_locations - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/me/locations' - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # V1LocationsApi + class V1LocationsApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Get a business's information. + # @return [V1Merchant Hash] response from the API call + def retrieve_business + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides details for a business's locations, including their IDs. + # @return [List of V1Merchant Hash] response from the API call + def list_locations + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/me/locations' + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api/v1_transactions_api.rb b/lib/square/api/v1_transactions_api.rb index 713835f2..e8f4f386 100644 --- a/lib/square/api/v1_transactions_api.rb +++ b/lib/square/api/v1_transactions_api.rb @@ -1,574 +1,574 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # V1TransactionsApi - class V1TransactionsApi < BaseApi - def initialize(config, http_call_back: nil) - super(config, http_call_back: http_call_back) - end - - # Provides non-confidential details for all of a location's associated bank - # accounts. This endpoint does not provide full bank account numbers, and - # there is no way to obtain a full bank account number with the Connect API. - # @param [String] location_id Required parameter: The ID of the location to - # list bank accounts for. - # @return [List of V1BankAccount Hash] response from the API call - def list_bank_accounts(location_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/bank-accounts' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides non-confidential details for a merchant's associated bank - # account. This endpoint does not provide full bank account numbers, and - # there is no way to obtain a full bank account number with the Connect API. - # @param [String] location_id Required parameter: The ID of the bank - # account's associated location. - # @param [String] bank_account_id Required parameter: The bank account's - # Square-issued ID. You obtain this value from Settlement objects - # returned. - # @return [V1BankAccount Hash] response from the API call - def retrieve_bank_account(location_id:, - bank_account_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/bank-accounts/{bank_account_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'bank_account_id' => bank_account_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides summary information for a merchant's online store orders. - # @param [String] location_id Required parameter: The ID of the location to - # list online store orders for. - # @param [SortOrder] order Optional parameter: TThe order in which payments - # are listed in the response. - # @param [Integer] limit Optional parameter: The maximum number of payments - # to return in a single response. This value cannot exceed 200. - # @param [String] batch_token Optional parameter: A pagination cursor to - # retrieve the next set of results for your original query to the - # endpoint. - # @return [List of V1Order Hash] response from the API call - def list_orders(location_id:, - order: nil, - limit: nil, - batch_token: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/orders' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'order' => order, - 'limit' => limit, - 'batch_token' => batch_token - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides comprehensive information for a single online store order, - # including the order's history. - # @param [String] location_id Required parameter: The ID of the order's - # associated location. - # @param [String] order_id Required parameter: The order's Square-issued ID. - # You obtain this value from Order objects returned by the List Orders - # endpoint - # @return [V1Order Hash] response from the API call - def retrieve_order(location_id:, - order_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/orders/{order_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'order_id' => order_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Updates the details of an online store order. Every update you perform on - # an order corresponds to one of three actions: - # @param [String] location_id Required parameter: The ID of the order's - # associated location. - # @param [String] order_id Required parameter: The order's Square-issued ID. - # You obtain this value from Order objects returned by the List Orders - # endpoint - # @param [V1UpdateOrderRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [V1Order Hash] response from the API call - def update_order(location_id:, - order_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/orders/{order_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'order_id' => order_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.put( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides summary information for all payments taken for a given - # Square account during a date range. Date ranges cannot exceed 1 year in - # length. See Date ranges for details of inclusive and exclusive dates. - # *Note**: Details for payments processed with Square Point of Sale while - # in offline mode may not be transmitted to Square for up to 72 hours. - # Offline payments have a `created_at` value that reflects the time the - # payment was originally processed, not the time it was subsequently - # transmitted to Square. Consequently, the ListPayments endpoint might - # list an offline payment chronologically between online payments that - # were seen in a previous request. - # @param [String] location_id Required parameter: The ID of the location to - # list payments for. If you specify me, this endpoint returns payments - # aggregated from all of the business's locations. - # @param [SortOrder] order Optional parameter: The order in which payments - # are listed in the response. - # @param [String] begin_time Optional parameter: The beginning of the - # requested reporting period, in ISO 8601 format. If this value is before - # January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. - # Default value: The current time minus one year. - # @param [String] end_time Optional parameter: The end of the requested - # reporting period, in ISO 8601 format. If this value is more than one year - # greater than begin_time, this endpoint returns an error. Default value: - # The current time. - # @param [Integer] limit Optional parameter: The maximum number of payments - # to return in a single response. This value cannot exceed 200. - # @param [String] batch_token Optional parameter: A pagination cursor to - # retrieve the next set of results for your original query to the - # endpoint. - # @param [Boolean] include_partial Optional parameter: Indicates whether or - # not to include partial payments in the response. Partial payments will - # have the tenders collected so far, but the itemizations will be empty - # until the payment is completed. - # @return [List of V1Payment Hash] response from the API call - def list_payments(location_id:, - order: nil, - begin_time: nil, - end_time: nil, - limit: nil, - batch_token: nil, - include_partial: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/payments' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'order' => order, - 'begin_time' => begin_time, - 'end_time' => end_time, - 'limit' => limit, - 'batch_token' => batch_token, - 'include_partial' => include_partial - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides comprehensive information for a single payment. - # @param [String] location_id Required parameter: The ID of the payment's - # associated location. - # @param [String] payment_id Required parameter: The Square-issued payment - # ID. payment_id comes from Payment objects returned by the List Payments - # endpoint, Settlement objects returned by the List Settlements endpoint, or - # Refund objects returned by the List Refunds endpoint. - # @return [V1Payment Hash] response from the API call - def retrieve_payment(location_id:, - payment_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/payments/{payment_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'payment_id' => payment_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides the details for all refunds initiated by a merchant or any of the - # merchant's mobile staff during a date range. Date ranges cannot exceed one - # year in length. - # @param [String] location_id Required parameter: The ID of the location to - # list refunds for. - # @param [SortOrder] order Optional parameter: TThe order in which payments - # are listed in the response. - # @param [String] begin_time Optional parameter: The beginning of the - # requested reporting period, in ISO 8601 format. If this value is before - # January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. - # Default value: The current time minus one year. - # @param [String] end_time Optional parameter: The end of the requested - # reporting period, in ISO 8601 format. If this value is more than one year - # greater than begin_time, this endpoint returns an error. Default value: - # The current time. - # @param [Integer] limit Optional parameter: The approximate number of - # refunds to return in a single response. Default: 100. Max: 200. Response - # may contain more results than the prescribed limit when refunds are made - # simultaneously to multiple tenders in a payment or when refunds are - # generated in an exchange to account for the value of returned goods. - # @param [String] batch_token Optional parameter: A pagination cursor to - # retrieve the next set of results for your original query to the - # endpoint. - # @return [List of V1Refund Hash] response from the API call - def list_refunds(location_id:, - order: nil, - begin_time: nil, - end_time: nil, - limit: nil, - batch_token: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/refunds' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'order' => order, - 'begin_time' => begin_time, - 'end_time' => end_time, - 'limit' => limit, - 'batch_token' => batch_token - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Issues a refund for a previously processed payment. You must issue - # a refund within 60 days of the associated payment. - # You cannot issue a partial refund for a split tender payment. You must - # instead issue a full or partial refund for a particular tender, by - # providing the applicable tender id to the V1CreateRefund endpoint. - # Issuing a full refund for a split tender payment refunds all tenders - # associated with the payment. - # Issuing a refund for a card payment is not reversible. For development - # purposes, you can create fake cash payments in Square Point of Sale and - # refund them. - # @param [String] location_id Required parameter: The ID of the original - # payment's associated location. - # @param [V1CreateRefundRequest] body Required parameter: An object - # containing the fields to POST for the request. See the corresponding - # object definition for field details. - # @return [V1Refund Hash] response from the API call - def create_refund(location_id:, - body:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/refunds' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.post( - _query_url, - headers: _headers, - parameters: body.to_json - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides summary information for all deposits and withdrawals - # initiated by Square to a linked bank account during a date range. Date - # ranges cannot exceed one year in length. - # *Note**: the ListSettlements endpoint does not provide entry - # information. - # @param [String] location_id Required parameter: The ID of the location to - # list settlements for. If you specify me, this endpoint returns payments - # aggregated from all of the business's locations. - # @param [SortOrder] order Optional parameter: TThe order in which payments - # are listed in the response. - # @param [String] begin_time Optional parameter: The beginning of the - # requested reporting period, in ISO 8601 format. If this value is before - # January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. - # Default value: The current time minus one year. - # @param [String] end_time Optional parameter: The end of the requested - # reporting period, in ISO 8601 format. If this value is more than one year - # greater than begin_time, this endpoint returns an error. Default value: - # The current time. - # @param [Integer] limit Optional parameter: The maximum number of payments - # to return in a single response. This value cannot exceed 200. - # @param [V1ListSettlementsRequestStatus] status Optional parameter: Provide - # this parameter to retrieve only settlements with a particular status (SENT - # or FAILED). - # @param [String] batch_token Optional parameter: A pagination cursor to - # retrieve the next set of results for your original query to the - # endpoint. - # @return [List of V1Settlement Hash] response from the API call - def list_settlements(location_id:, - order: nil, - begin_time: nil, - end_time: nil, - limit: nil, - status: nil, - batch_token: nil) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/settlements' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id - ) - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - 'order' => order, - 'begin_time' => begin_time, - 'end_time' => end_time, - 'limit' => limit, - 'status' => status, - 'batch_token' => batch_token - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - - # Provides comprehensive information for a single settlement. - # The returned `Settlement` objects include an `entries` field that lists - # the transactions that contribute to the settlement total. Most - # settlement entries correspond to a payment payout, but settlement - # entries are also generated for less common events, like refunds, manual - # adjustments, or chargeback holds. - # Square initiates its regular deposits as indicated in the - # [Deposit Options with - # Square](https://squareup.com/help/us/en/article/3807) - # help article. Details for a regular deposit are usually not available - # from Connect API endpoints before 10 p.m. PST the same day. - # Square does not know when an initiated settlement **completes**, only - # whether it has failed. A completed settlement is typically reflected in - # a bank account within 3 business days, but in exceptional cases it may - # take longer. - # @param [String] location_id Required parameter: The ID of the - # settlements's associated location. - # @param [String] settlement_id Required parameter: The settlement's - # Square-issued ID. You obtain this value from Settlement objects returned - # by the List Settlements endpoint. - # @return [V1Settlement Hash] response from the API call - def retrieve_settlement(location_id:, - settlement_id:) - # Prepare query url. - _query_builder = config.get_base_uri - _query_builder << '/v1/{location_id}/settlements/{settlement_id}' - _query_builder = APIHelper.append_url_with_template_parameters( - _query_builder, - 'location_id' => location_id, - 'settlement_id' => settlement_id - ) - _query_url = APIHelper.clean_url _query_builder - - # Prepare headers. - _headers = { - 'accept' => 'application/json' - } - - # Prepare and execute HttpRequest. - _request = config.http_client.get( - _query_url, - headers: _headers - ) - OAuth2.apply(config, _request) - _response = execute_request(_request) - - # Return appropriate response type. - decoded = APIHelper.json_deserialize(_response.raw_body) - _errors = APIHelper.map_response(decoded, ['errors']) - ApiResponse.new(_response, data: decoded, errors: _errors) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # V1TransactionsApi + class V1TransactionsApi < BaseApi + def initialize(config, http_call_back: nil) + super(config, http_call_back: http_call_back) + end + + # Provides non-confidential details for all of a location's associated bank + # accounts. This endpoint does not provide full bank account numbers, and + # there is no way to obtain a full bank account number with the Connect API. + # @param [String] location_id Required parameter: The ID of the location to + # list bank accounts for. + # @return [List of V1BankAccount Hash] response from the API call + def list_bank_accounts(location_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/bank-accounts' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides non-confidential details for a merchant's associated bank + # account. This endpoint does not provide full bank account numbers, and + # there is no way to obtain a full bank account number with the Connect API. + # @param [String] location_id Required parameter: The ID of the bank + # account's associated location. + # @param [String] bank_account_id Required parameter: The bank account's + # Square-issued ID. You obtain this value from Settlement objects + # returned. + # @return [V1BankAccount Hash] response from the API call + def retrieve_bank_account(location_id:, + bank_account_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/bank-accounts/{bank_account_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'bank_account_id' => bank_account_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides summary information for a merchant's online store orders. + # @param [String] location_id Required parameter: The ID of the location to + # list online store orders for. + # @param [SortOrder] order Optional parameter: TThe order in which payments + # are listed in the response. + # @param [Integer] limit Optional parameter: The maximum number of payments + # to return in a single response. This value cannot exceed 200. + # @param [String] batch_token Optional parameter: A pagination cursor to + # retrieve the next set of results for your original query to the + # endpoint. + # @return [List of V1Order Hash] response from the API call + def list_orders(location_id:, + order: nil, + limit: nil, + batch_token: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/orders' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'order' => order, + 'limit' => limit, + 'batch_token' => batch_token + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides comprehensive information for a single online store order, + # including the order's history. + # @param [String] location_id Required parameter: The ID of the order's + # associated location. + # @param [String] order_id Required parameter: The order's Square-issued ID. + # You obtain this value from Order objects returned by the List Orders + # endpoint + # @return [V1Order Hash] response from the API call + def retrieve_order(location_id:, + order_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/orders/{order_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'order_id' => order_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Updates the details of an online store order. Every update you perform on + # an order corresponds to one of three actions: + # @param [String] location_id Required parameter: The ID of the order's + # associated location. + # @param [String] order_id Required parameter: The order's Square-issued ID. + # You obtain this value from Order objects returned by the List Orders + # endpoint + # @param [V1UpdateOrderRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [V1Order Hash] response from the API call + def update_order(location_id:, + order_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/orders/{order_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'order_id' => order_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.put( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides summary information for all payments taken for a given + # Square account during a date range. Date ranges cannot exceed 1 year in + # length. See Date ranges for details of inclusive and exclusive dates. + # *Note**: Details for payments processed with Square Point of Sale while + # in offline mode may not be transmitted to Square for up to 72 hours. + # Offline payments have a `created_at` value that reflects the time the + # payment was originally processed, not the time it was subsequently + # transmitted to Square. Consequently, the ListPayments endpoint might + # list an offline payment chronologically between online payments that + # were seen in a previous request. + # @param [String] location_id Required parameter: The ID of the location to + # list payments for. If you specify me, this endpoint returns payments + # aggregated from all of the business's locations. + # @param [SortOrder] order Optional parameter: The order in which payments + # are listed in the response. + # @param [String] begin_time Optional parameter: The beginning of the + # requested reporting period, in ISO 8601 format. If this value is before + # January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. + # Default value: The current time minus one year. + # @param [String] end_time Optional parameter: The end of the requested + # reporting period, in ISO 8601 format. If this value is more than one year + # greater than begin_time, this endpoint returns an error. Default value: + # The current time. + # @param [Integer] limit Optional parameter: The maximum number of payments + # to return in a single response. This value cannot exceed 200. + # @param [String] batch_token Optional parameter: A pagination cursor to + # retrieve the next set of results for your original query to the + # endpoint. + # @param [Boolean] include_partial Optional parameter: Indicates whether or + # not to include partial payments in the response. Partial payments will + # have the tenders collected so far, but the itemizations will be empty + # until the payment is completed. + # @return [List of V1Payment Hash] response from the API call + def list_payments(location_id:, + order: nil, + begin_time: nil, + end_time: nil, + limit: nil, + batch_token: nil, + include_partial: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/payments' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'order' => order, + 'begin_time' => begin_time, + 'end_time' => end_time, + 'limit' => limit, + 'batch_token' => batch_token, + 'include_partial' => include_partial + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides comprehensive information for a single payment. + # @param [String] location_id Required parameter: The ID of the payment's + # associated location. + # @param [String] payment_id Required parameter: The Square-issued payment + # ID. payment_id comes from Payment objects returned by the List Payments + # endpoint, Settlement objects returned by the List Settlements endpoint, or + # Refund objects returned by the List Refunds endpoint. + # @return [V1Payment Hash] response from the API call + def retrieve_payment(location_id:, + payment_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/payments/{payment_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'payment_id' => payment_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides the details for all refunds initiated by a merchant or any of the + # merchant's mobile staff during a date range. Date ranges cannot exceed one + # year in length. + # @param [String] location_id Required parameter: The ID of the location to + # list refunds for. + # @param [SortOrder] order Optional parameter: TThe order in which payments + # are listed in the response. + # @param [String] begin_time Optional parameter: The beginning of the + # requested reporting period, in ISO 8601 format. If this value is before + # January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. + # Default value: The current time minus one year. + # @param [String] end_time Optional parameter: The end of the requested + # reporting period, in ISO 8601 format. If this value is more than one year + # greater than begin_time, this endpoint returns an error. Default value: + # The current time. + # @param [Integer] limit Optional parameter: The approximate number of + # refunds to return in a single response. Default: 100. Max: 200. Response + # may contain more results than the prescribed limit when refunds are made + # simultaneously to multiple tenders in a payment or when refunds are + # generated in an exchange to account for the value of returned goods. + # @param [String] batch_token Optional parameter: A pagination cursor to + # retrieve the next set of results for your original query to the + # endpoint. + # @return [List of V1Refund Hash] response from the API call + def list_refunds(location_id:, + order: nil, + begin_time: nil, + end_time: nil, + limit: nil, + batch_token: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/refunds' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'order' => order, + 'begin_time' => begin_time, + 'end_time' => end_time, + 'limit' => limit, + 'batch_token' => batch_token + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Issues a refund for a previously processed payment. You must issue + # a refund within 60 days of the associated payment. + # You cannot issue a partial refund for a split tender payment. You must + # instead issue a full or partial refund for a particular tender, by + # providing the applicable tender id to the V1CreateRefund endpoint. + # Issuing a full refund for a split tender payment refunds all tenders + # associated with the payment. + # Issuing a refund for a card payment is not reversible. For development + # purposes, you can create fake cash payments in Square Point of Sale and + # refund them. + # @param [String] location_id Required parameter: The ID of the original + # payment's associated location. + # @param [V1CreateRefundRequest] body Required parameter: An object + # containing the fields to POST for the request. See the corresponding + # object definition for field details. + # @return [V1Refund Hash] response from the API call + def create_refund(location_id:, + body:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/refunds' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.post( + _query_url, + headers: _headers, + parameters: body.to_json + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides summary information for all deposits and withdrawals + # initiated by Square to a linked bank account during a date range. Date + # ranges cannot exceed one year in length. + # *Note**: the ListSettlements endpoint does not provide entry + # information. + # @param [String] location_id Required parameter: The ID of the location to + # list settlements for. If you specify me, this endpoint returns payments + # aggregated from all of the business's locations. + # @param [SortOrder] order Optional parameter: TThe order in which payments + # are listed in the response. + # @param [String] begin_time Optional parameter: The beginning of the + # requested reporting period, in ISO 8601 format. If this value is before + # January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. + # Default value: The current time minus one year. + # @param [String] end_time Optional parameter: The end of the requested + # reporting period, in ISO 8601 format. If this value is more than one year + # greater than begin_time, this endpoint returns an error. Default value: + # The current time. + # @param [Integer] limit Optional parameter: The maximum number of payments + # to return in a single response. This value cannot exceed 200. + # @param [V1ListSettlementsRequestStatus] status Optional parameter: Provide + # this parameter to retrieve only settlements with a particular status (SENT + # or FAILED). + # @param [String] batch_token Optional parameter: A pagination cursor to + # retrieve the next set of results for your original query to the + # endpoint. + # @return [List of V1Settlement Hash] response from the API call + def list_settlements(location_id:, + order: nil, + begin_time: nil, + end_time: nil, + limit: nil, + status: nil, + batch_token: nil) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/settlements' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id + ) + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + 'order' => order, + 'begin_time' => begin_time, + 'end_time' => end_time, + 'limit' => limit, + 'status' => status, + 'batch_token' => batch_token + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + + # Provides comprehensive information for a single settlement. + # The returned `Settlement` objects include an `entries` field that lists + # the transactions that contribute to the settlement total. Most + # settlement entries correspond to a payment payout, but settlement + # entries are also generated for less common events, like refunds, manual + # adjustments, or chargeback holds. + # Square initiates its regular deposits as indicated in the + # [Deposit Options with + # Square](https://squareup.com/help/us/en/article/3807) + # help article. Details for a regular deposit are usually not available + # from Connect API endpoints before 10 p.m. PST the same day. + # Square does not know when an initiated settlement **completes**, only + # whether it has failed. A completed settlement is typically reflected in + # a bank account within 3 business days, but in exceptional cases it may + # take longer. + # @param [String] location_id Required parameter: The ID of the + # settlements's associated location. + # @param [String] settlement_id Required parameter: The settlement's + # Square-issued ID. You obtain this value from Settlement objects returned + # by the List Settlements endpoint. + # @return [V1Settlement Hash] response from the API call + def retrieve_settlement(location_id:, + settlement_id:) + # Prepare query url. + _query_builder = config.get_base_uri + _query_builder << '/v1/{location_id}/settlements/{settlement_id}' + _query_builder = APIHelper.append_url_with_template_parameters( + _query_builder, + 'location_id' => location_id, + 'settlement_id' => settlement_id + ) + _query_url = APIHelper.clean_url _query_builder + + # Prepare headers. + _headers = { + 'accept' => 'application/json' + } + + # Prepare and execute HttpRequest. + _request = config.http_client.get( + _query_url, + headers: _headers + ) + OAuth2.apply(config, _request) + _response = execute_request(_request) + + # Return appropriate response type. + decoded = APIHelper.json_deserialize(_response.raw_body) + _errors = APIHelper.map_response(decoded, ['errors']) + ApiResponse.new(_response, data: decoded, errors: _errors) + end + end +end diff --git a/lib/square/api_helper.rb b/lib/square/api_helper.rb index 1b29ce98..62f9d00b 100644 --- a/lib/square/api_helper.rb +++ b/lib/square/api_helper.rb @@ -1,281 +1,281 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # API utility class - class APIHelper - # Serializes an array parameter (creates key value pairs). - # @param [String] The name of the parameter. - # @param [Array] The value of the parameter. - # @param [String] The format of the serialization. - def self.serialize_array(key, array, formatting: 'indexed') - tuples = [] - - if formatting == 'unindexed' - tuples += array.map { |element| ["#{key}[]", element] } - elsif formatting == 'indexed' - tuples += array.map.with_index do |element, index| - ["#{key}[#{index}]", element] - end - elsif formatting == 'plain' - tuples += array.map { |element| [key, element] } - else - raise ArgumentError, 'Invalid format provided.' - end - tuples - end - - # Replaces template parameters in the given url. - # @param [String] The query string builder to replace the template - # parameters. - # @param [Hash] The parameters to replace in the url. - def self.append_url_with_template_parameters(query_builder, parameters) - # perform parameter validation - unless query_builder.instance_of? String - raise ArgumentError, 'Given value for parameter \"query_builder\" is - invalid.' - end - - # Return if there are no parameters to replace. - return query_builder if parameters.nil? - - # Iterate and append parameters. - parameters.each do |key, value| - replace_value = '' - - if value.nil? - replace_value = '' - elsif value.instance_of? Array - value.map! { |element| CGI.escape(element.to_s) } - replace_value = value.join('/') - else - replace_value = CGI.escape(value.to_s) - end - - # Find the template parameter and replace it with its value. - query_builder = query_builder.gsub('{' + key.to_s + '}', replace_value) - end - query_builder - end - - # Appends the given set of parameters to the given query string. - # @param [String] The query string builder to add the query parameters to. - # @param [Hash] The parameters to append. - # @param [String] The format of array parameter serialization. - def self.append_url_with_query_parameters(query_builder, parameters, - array_serialization: 'indexed') - # Perform parameter validation. - unless query_builder.instance_of? String - raise ArgumentError, 'Given value for parameter \"query_builder\" - is invalid.' - end - - # Return if there are no parameters to replace. - return query_builder if parameters.nil? - - parameters.each do |key, value| - seperator = query_builder.include?('?') ? '&' : '?' - unless value.nil? - if value.instance_of? Array - value.compact! - query_builder += if array_serialization == 'csv' - "#{seperator}#{key}=#{value.map do |element| - CGI.escape(element.to_s) - end.join(',')}" - elsif array_serialization == 'psv' - "#{seperator}#{key}=#{value.map do |element| - CGI.escape(element.to_s) - end.join('|')}" - elsif array_serialization == 'tsv' - "#{seperator}#{key}=#{value.map do |element| - CGI.escape(element.to_s) - end.join("\t")}" - else - "#{seperator}#{APIHelper.serialize_array( - key, value, formatting: array_serialization - ).map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" } - .join('&')}" - end - else - query_builder += "#{seperator}#{key}=#{CGI.escape(value.to_s)}" - end - end - end - query_builder - end - - # Validates and processes the given Url. - # @param [String] The given Url to process. - # @return [String] Pre-processed Url as string. - def self.clean_url(url) - # Perform parameter validation. - raise ArgumentError, 'Invalid Url.' unless url.instance_of? String - - # Ensure that the urls are absolute. - matches = url.match(%r{^(https?:\/\/[^\/]+)}) - raise ArgumentError, 'Invalid Url format.' if matches.nil? - - # Get the http protocol match. - protocol = matches[1] - - # Check if parameters exist. - index = url.index('?') - - # Remove redundant forward slashes. - query = url[protocol.length...(!index.nil? ? index : url.length)] - query.gsub!(%r{\/\/+}, '/') - - # Get the parameters. - parameters = !index.nil? ? url[url.index('?')...url.length] : '' - - # Return processed url. - protocol + query + parameters - end - - # Parses JSON string. - # @param [String] A JSON string. - def self.json_deserialize(json) - return JSON.parse(json, symbolize_names: true) - rescue StandardError - raise TypeError, 'Server responded with invalid JSON.' - end - - # Removes elements with empty values from a hash. - # @param [Hash] The hash to clean. - def self.clean_hash(hash) - hash.delete_if { |_key, value| value.to_s.strip.empty? } - end - - # Form encodes a hash of parameters. - # @param [Hash] The hash of parameters to encode. - # @return [Hash] A hash with the same parameters form encoded. - def self.form_encode_parameters(form_parameters, - array_serialization: 'indexed') - encoded = {} - form_parameters.each do |key, value| - encoded.merge!(APIHelper.form_encode(value, key, formatting: - array_serialization)) - end - encoded - end - - def self.custom_merge(a, b) - x = {} - a.each do |key, value_a| - b.each do |k, value_b| - next unless key == k - x[k] = [] - if value_a.instance_of? Array - value_a.each do |v| - x[k].push(v) - end - else - x[k].push(value_a) - end - if value_b.instance_of? Array - value_b.each do |v| - x[k].push(v) - end - else - x[k].push(value_b) - end - a.delete(k) - b.delete(k) - end - end - x.merge!(a) - x.merge!(b) - x - end - - # Form encodes an object. - # @param [Dynamic] An object to form encode. - # @param [String] The name of the object. - # @return [Hash] A form encoded representation of the object in the form - # of a hash. - def self.form_encode(obj, instance_name, formatting: 'indexed') - retval = {} - - serializable_types = [String, Numeric, TrueClass, - FalseClass, Date, DateTime] - - # Create a form encoded hash for this object. - if obj.nil? - nil - elsif obj.instance_of? Array - if formatting == 'indexed' - obj.each_with_index do |value, index| - retval.merge!(APIHelper.form_encode(value, instance_name + '[' + - index.to_s + ']')) - end - elsif serializable_types.map { |x| obj[0].is_a? x }.any? - obj.each do |value| - abc = if formatting == 'unindexed' - APIHelper.form_encode(value, instance_name + '[]', - formatting: formatting) - else - APIHelper.form_encode(value, instance_name, - formatting: formatting) - end - retval = APIHelper.custom_merge(retval, abc) - end - else - obj.each_with_index do |value, index| - retval.merge!(APIHelper.form_encode(value, instance_name + '[' + - index.to_s + ']', formatting: formatting)) - end - end - elsif obj.instance_of? Hash - obj.each do |key, value| - retval.merge!(APIHelper.form_encode(value, instance_name + '[' + - key.to_s + ']', formatting: formatting)) - end - elsif obj.instance_of? File - retval[instance_name] = UploadIO.new( - obj, 'application/octet-stream', File.basename(obj.path) - ) - else - retval[instance_name] = obj - end - retval - end - - # Retrieves a field from a Hash/Array based on an Array of keys/indexes - # @param [Hash, Array] The hash to extract data from - # @param [Array] The keys/indexes to use - # @return [Object] The extracted value - def self.map_response(obj, keys) - val = obj - begin - keys.each do |key| - val = if val.is_a? Array - if key.to_i.to_s == key - val[key.to_i] - else - val = nil - end - else - val.fetch(key.to_sym) - end - end - rescue NoMethodError, TypeError, IndexError - val = nil - end - val - end - - # Safely converts a string into an rfc3339 DateTime object - # @param [String] The datetime string - # @return [DateTime] A DateTime object of rfc3339 format - def self.rfc3339(date_time) - # missing timezone information - if date_time.end_with?('Z') || date_time.index('+') - DateTime.rfc3339(date_time) - else - DateTime.rfc3339(date_time + 'Z') - end - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # API utility class + class APIHelper + # Serializes an array parameter (creates key value pairs). + # @param [String] The name of the parameter. + # @param [Array] The value of the parameter. + # @param [String] The format of the serialization. + def self.serialize_array(key, array, formatting: 'indexed') + tuples = [] + + if formatting == 'unindexed' + tuples += array.map { |element| ["#{key}[]", element] } + elsif formatting == 'indexed' + tuples += array.map.with_index do |element, index| + ["#{key}[#{index}]", element] + end + elsif formatting == 'plain' + tuples += array.map { |element| [key, element] } + else + raise ArgumentError, 'Invalid format provided.' + end + tuples + end + + # Replaces template parameters in the given url. + # @param [String] The query string builder to replace the template + # parameters. + # @param [Hash] The parameters to replace in the url. + def self.append_url_with_template_parameters(query_builder, parameters) + # perform parameter validation + unless query_builder.instance_of? String + raise ArgumentError, 'Given value for parameter \"query_builder\" is + invalid.' + end + + # Return if there are no parameters to replace. + return query_builder if parameters.nil? + + # Iterate and append parameters. + parameters.each do |key, value| + replace_value = '' + + if value.nil? + replace_value = '' + elsif value.instance_of? Array + value.map! { |element| CGI.escape(element.to_s) } + replace_value = value.join('/') + else + replace_value = CGI.escape(value.to_s) + end + + # Find the template parameter and replace it with its value. + query_builder = query_builder.gsub('{' + key.to_s + '}', replace_value) + end + query_builder + end + + # Appends the given set of parameters to the given query string. + # @param [String] The query string builder to add the query parameters to. + # @param [Hash] The parameters to append. + # @param [String] The format of array parameter serialization. + def self.append_url_with_query_parameters(query_builder, parameters, + array_serialization: 'indexed') + # Perform parameter validation. + unless query_builder.instance_of? String + raise ArgumentError, 'Given value for parameter \"query_builder\" + is invalid.' + end + + # Return if there are no parameters to replace. + return query_builder if parameters.nil? + + parameters.each do |key, value| + seperator = query_builder.include?('?') ? '&' : '?' + unless value.nil? + if value.instance_of? Array + value.compact! + query_builder += if array_serialization == 'csv' + "#{seperator}#{key}=#{value.map do |element| + CGI.escape(element.to_s) + end.join(',')}" + elsif array_serialization == 'psv' + "#{seperator}#{key}=#{value.map do |element| + CGI.escape(element.to_s) + end.join('|')}" + elsif array_serialization == 'tsv' + "#{seperator}#{key}=#{value.map do |element| + CGI.escape(element.to_s) + end.join("\t")}" + else + "#{seperator}#{APIHelper.serialize_array( + key, value, formatting: array_serialization + ).map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" } + .join('&')}" + end + else + query_builder += "#{seperator}#{key}=#{CGI.escape(value.to_s)}" + end + end + end + query_builder + end + + # Validates and processes the given Url. + # @param [String] The given Url to process. + # @return [String] Pre-processed Url as string. + def self.clean_url(url) + # Perform parameter validation. + raise ArgumentError, 'Invalid Url.' unless url.instance_of? String + + # Ensure that the urls are absolute. + matches = url.match(%r{^(https?:\/\/[^\/]+)}) + raise ArgumentError, 'Invalid Url format.' if matches.nil? + + # Get the http protocol match. + protocol = matches[1] + + # Check if parameters exist. + index = url.index('?') + + # Remove redundant forward slashes. + query = url[protocol.length...(!index.nil? ? index : url.length)] + query.gsub!(%r{\/\/+}, '/') + + # Get the parameters. + parameters = !index.nil? ? url[url.index('?')...url.length] : '' + + # Return processed url. + protocol + query + parameters + end + + # Parses JSON string. + # @param [String] A JSON string. + def self.json_deserialize(json) + return JSON.parse(json, symbolize_names: true) + rescue StandardError + raise TypeError, 'Server responded with invalid JSON.' + end + + # Removes elements with empty values from a hash. + # @param [Hash] The hash to clean. + def self.clean_hash(hash) + hash.delete_if { |_key, value| value.to_s.strip.empty? } + end + + # Form encodes a hash of parameters. + # @param [Hash] The hash of parameters to encode. + # @return [Hash] A hash with the same parameters form encoded. + def self.form_encode_parameters(form_parameters, + array_serialization: 'indexed') + encoded = {} + form_parameters.each do |key, value| + encoded.merge!(APIHelper.form_encode(value, key, formatting: + array_serialization)) + end + encoded + end + + def self.custom_merge(a, b) + x = {} + a.each do |key, value_a| + b.each do |k, value_b| + next unless key == k + x[k] = [] + if value_a.instance_of? Array + value_a.each do |v| + x[k].push(v) + end + else + x[k].push(value_a) + end + if value_b.instance_of? Array + value_b.each do |v| + x[k].push(v) + end + else + x[k].push(value_b) + end + a.delete(k) + b.delete(k) + end + end + x.merge!(a) + x.merge!(b) + x + end + + # Form encodes an object. + # @param [Dynamic] An object to form encode. + # @param [String] The name of the object. + # @return [Hash] A form encoded representation of the object in the form + # of a hash. + def self.form_encode(obj, instance_name, formatting: 'indexed') + retval = {} + + serializable_types = [String, Numeric, TrueClass, + FalseClass, Date, DateTime] + + # Create a form encoded hash for this object. + if obj.nil? + nil + elsif obj.instance_of? Array + if formatting == 'indexed' + obj.each_with_index do |value, index| + retval.merge!(APIHelper.form_encode(value, instance_name + '[' + + index.to_s + ']')) + end + elsif serializable_types.map { |x| obj[0].is_a? x }.any? + obj.each do |value| + abc = if formatting == 'unindexed' + APIHelper.form_encode(value, instance_name + '[]', + formatting: formatting) + else + APIHelper.form_encode(value, instance_name, + formatting: formatting) + end + retval = APIHelper.custom_merge(retval, abc) + end + else + obj.each_with_index do |value, index| + retval.merge!(APIHelper.form_encode(value, instance_name + '[' + + index.to_s + ']', formatting: formatting)) + end + end + elsif obj.instance_of? Hash + obj.each do |key, value| + retval.merge!(APIHelper.form_encode(value, instance_name + '[' + + key.to_s + ']', formatting: formatting)) + end + elsif obj.instance_of? File + retval[instance_name] = UploadIO.new( + obj, 'application/octet-stream', File.basename(obj.path) + ) + else + retval[instance_name] = obj + end + retval + end + + # Retrieves a field from a Hash/Array based on an Array of keys/indexes + # @param [Hash, Array] The hash to extract data from + # @param [Array] The keys/indexes to use + # @return [Object] The extracted value + def self.map_response(obj, keys) + val = obj + begin + keys.each do |key| + val = if val.is_a? Array + if key.to_i.to_s == key + val[key.to_i] + else + val = nil + end + else + val.fetch(key.to_sym) + end + end + rescue NoMethodError, TypeError, IndexError + val = nil + end + val + end + + # Safely converts a string into an rfc3339 DateTime object + # @param [String] The datetime string + # @return [DateTime] A DateTime object of rfc3339 format + def self.rfc3339(date_time) + # missing timezone information + if date_time.end_with?('Z') || date_time.index('+') + DateTime.rfc3339(date_time) + else + DateTime.rfc3339(date_time + 'Z') + end + end + end +end diff --git a/lib/square/client.rb b/lib/square/client.rb index 797e0a40..62c90fb1 100644 --- a/lib/square/client.rb +++ b/lib/square/client.rb @@ -1,139 +1,155 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # square client class. - class Client - attr_reader :config - - # Access to mobile_authorization controller. - # @return [MobileAuthorizationApi] Returns the controller instance. - def mobile_authorization - @mobile_authorization ||= MobileAuthorizationApi.new config - end - - # Access to o_auth controller. - # @return [OAuthApi] Returns the controller instance. - def o_auth - @o_auth ||= OAuthApi.new config - end - - # Access to v1_locations controller. - # @return [V1LocationsApi] Returns the controller instance. - def v1_locations - @v1_locations ||= V1LocationsApi.new config - end - - # Access to v1_employees controller. - # @return [V1EmployeesApi] Returns the controller instance. - def v1_employees - @v1_employees ||= V1EmployeesApi.new config - end - - # Access to v1_transactions controller. - # @return [V1TransactionsApi] Returns the controller instance. - def v1_transactions - @v1_transactions ||= V1TransactionsApi.new config - end - - # Access to v1_items controller. - # @return [V1ItemsApi] Returns the controller instance. - def v1_items - @v1_items ||= V1ItemsApi.new config - end - - # Access to apple_pay controller. - # @return [ApplePayApi] Returns the controller instance. - def apple_pay - @apple_pay ||= ApplePayApi.new config - end - - # Access to catalog controller. - # @return [CatalogApi] Returns the controller instance. - def catalog - @catalog ||= CatalogApi.new config - end - - # Access to customers controller. - # @return [CustomersApi] Returns the controller instance. - def customers - @customers ||= CustomersApi.new config - end - - # Access to employees controller. - # @return [EmployeesApi] Returns the controller instance. - def employees - @employees ||= EmployeesApi.new config - end - - # Access to inventory controller. - # @return [InventoryApi] Returns the controller instance. - def inventory - @inventory ||= InventoryApi.new config - end - - # Access to labor controller. - # @return [LaborApi] Returns the controller instance. - def labor - @labor ||= LaborApi.new config - end - - # Access to locations controller. - # @return [LocationsApi] Returns the controller instance. - def locations - @locations ||= LocationsApi.new config - end - - # Access to reporting controller. - # @return [ReportingApi] Returns the controller instance. - def reporting - @reporting ||= ReportingApi.new config - end - - # Access to checkout controller. - # @return [CheckoutApi] Returns the controller instance. - def checkout - @checkout ||= CheckoutApi.new config - end - - # Access to orders controller. - # @return [OrdersApi] Returns the controller instance. - def orders - @orders ||= OrdersApi.new config - end - - # Access to transactions controller. - # @return [TransactionsApi] Returns the controller instance. - def transactions - @transactions ||= TransactionsApi.new config - end - - # Access to payments controller. - # @return [PaymentsApi] Returns the controller instance. - def payments - @payments ||= PaymentsApi.new config - end - - # Access to refunds controller. - # @return [RefundsApi] Returns the controller instance. - def refunds - @refunds ||= RefundsApi.new config - end - - def initialize(timeout: 60, max_retries: 0, retry_interval: 1, - backoff_factor: 1, environment: 'production', - access_token: 'TODO: Replace', config: nil) - @config = if config.nil? - Configuration.new(timeout: timeout, max_retries: max_retries, - retry_interval: retry_interval, - backoff_factor: backoff_factor, - environment: environment, - access_token: access_token) - else - config - end - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # square client class. + class Client + attr_reader :config + + def sdk_version + '3.20190925.0' + end + + def square_version + '2019-09-25' + end + + # Access to mobile_authorization controller. + # @return [MobileAuthorizationApi] Returns the controller instance. + def mobile_authorization + @mobile_authorization ||= MobileAuthorizationApi.new config + end + + # Access to o_auth controller. + # @return [OAuthApi] Returns the controller instance. + def o_auth + @o_auth ||= OAuthApi.new config + end + + # Access to v1_locations controller. + # @return [V1LocationsApi] Returns the controller instance. + def v1_locations + @v1_locations ||= V1LocationsApi.new config + end + + # Access to v1_employees controller. + # @return [V1EmployeesApi] Returns the controller instance. + def v1_employees + @v1_employees ||= V1EmployeesApi.new config + end + + # Access to v1_transactions controller. + # @return [V1TransactionsApi] Returns the controller instance. + def v1_transactions + @v1_transactions ||= V1TransactionsApi.new config + end + + # Access to v1_items controller. + # @return [V1ItemsApi] Returns the controller instance. + def v1_items + @v1_items ||= V1ItemsApi.new config + end + + # Access to apple_pay controller. + # @return [ApplePayApi] Returns the controller instance. + def apple_pay + @apple_pay ||= ApplePayApi.new config + end + + # Access to catalog controller. + # @return [CatalogApi] Returns the controller instance. + def catalog + @catalog ||= CatalogApi.new config + end + + # Access to customers controller. + # @return [CustomersApi] Returns the controller instance. + def customers + @customers ||= CustomersApi.new config + end + + # Access to employees controller. + # @return [EmployeesApi] Returns the controller instance. + def employees + @employees ||= EmployeesApi.new config + end + + # Access to inventory controller. + # @return [InventoryApi] Returns the controller instance. + def inventory + @inventory ||= InventoryApi.new config + end + + # Access to labor controller. + # @return [LaborApi] Returns the controller instance. + def labor + @labor ||= LaborApi.new config + end + + # Access to locations controller. + # @return [LocationsApi] Returns the controller instance. + def locations + @locations ||= LocationsApi.new config + end + + # Access to reporting controller. + # @return [ReportingApi] Returns the controller instance. + def reporting + @reporting ||= ReportingApi.new config + end + + # Access to checkout controller. + # @return [CheckoutApi] Returns the controller instance. + def checkout + @checkout ||= CheckoutApi.new config + end + + # Access to orders controller. + # @return [OrdersApi] Returns the controller instance. + def orders + @orders ||= OrdersApi.new config + end + + # Access to transactions controller. + # @return [TransactionsApi] Returns the controller instance. + def transactions + @transactions ||= TransactionsApi.new config + end + + # Access to merchants controller. + # @return [MerchantsApi] Returns the controller instance. + def merchants + @merchants ||= MerchantsApi.new config + end + + # Access to payments controller. + # @return [PaymentsApi] Returns the controller instance. + def payments + @payments ||= PaymentsApi.new config + end + + # Access to refunds controller. + # @return [RefundsApi] Returns the controller instance. + def refunds + @refunds ||= RefundsApi.new config + end + + def initialize(timeout: 60, max_retries: 0, retry_interval: 1, + backoff_factor: 1, environment: 'production', + access_token: 'TODO: Replace', additional_headers: {}, + config: nil) + @config = if config.nil? + Configuration.new(timeout: timeout, max_retries: max_retries, + retry_interval: retry_interval, + backoff_factor: backoff_factor, + environment: environment, + access_token: access_token, + additional_headers: additional_headers) + else + config + end + end + end +end diff --git a/lib/square/configuration.rb b/lib/square/configuration.rb index caec2490..acf47caa 100644 --- a/lib/square/configuration.rb +++ b/lib/square/configuration.rb @@ -1,88 +1,98 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # All configuration including auth info and base URI for the API access - # are configured in this class. - class Configuration - # The attribute readers for properties. - attr_reader :http_client - attr_reader :timeout - attr_reader :max_retries - attr_reader :retry_interval - attr_reader :backoff_factor - attr_reader :environment - attr_reader :access_token - - class << self - attr_reader :environments - end - - def initialize(timeout: 60, max_retries: 0, retry_interval: 1, - backoff_factor: 1, environment: 'production', - access_token: 'TODO: Replace') - # The value to use for connection timeout - @timeout = timeout - - # The number of times to retry an endpoint call if it fails - @max_retries = max_retries - - # Pause in seconds between retries - @retry_interval = retry_interval - - # The amount to multiply each successive retry's interval amount - # by in order to provide backoff - @backoff_factor = backoff_factor - - # Current API environment - @environment = environment - - # OAuth 2.0 Access Token - @access_token = access_token - - # The Http Client to use for making requests. - @http_client = create_http_client - end - - def clone_with(timeout: nil, max_retries: nil, retry_interval: nil, - backoff_factor: nil, environment: nil, access_token: nil) - timeout ||= self.timeout - max_retries ||= self.max_retries - retry_interval ||= self.retry_interval - backoff_factor ||= self.backoff_factor - environment ||= self.environment - access_token ||= self.access_token - - Configuration.new(timeout: timeout, max_retries: max_retries, - retry_interval: retry_interval, - backoff_factor: backoff_factor, - environment: environment, access_token: access_token) - end - - def create_http_client - FaradayClient.new(timeout: timeout, max_retries: max_retries, - retry_interval: retry_interval, - backoff_factor: backoff_factor) - end - - # All the environments the SDK can run in. - @environments = { - 'production' => { - 'default' => 'https://connect.squareup.com' - }, - 'sandbox' => { - 'default' => 'https://connect.squareupsandbox.com' - } - } - - # Generates the appropriate base URI for the environment and the server. - # @param [Configuration::Server] The server enum for which the base URI is - # required. - # @return [String] The base URI. - def get_base_uri(server = 'default') - self.class.environments[environment][server].clone - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # All configuration including auth info and base URI for the API access + # are configured in this class. + class Configuration + # The attribute readers for properties. + attr_reader :http_client + attr_reader :timeout + attr_reader :max_retries + attr_reader :retry_interval + attr_reader :backoff_factor + attr_reader :environment + attr_reader :access_token + + def additional_headers + @additional_headers.clone + end + + class << self + attr_reader :environments + end + + def initialize(timeout: 60, max_retries: 0, retry_interval: 1, + backoff_factor: 1, environment: 'production', + access_token: 'TODO: Replace', additional_headers: {}) + # The value to use for connection timeout + @timeout = timeout + + # The number of times to retry an endpoint call if it fails + @max_retries = max_retries + + # Pause in seconds between retries + @retry_interval = retry_interval + + # The amount to multiply each successive retry's interval amount + # by in order to provide backoff + @backoff_factor = backoff_factor + + # Current API environment + @environment = environment + + # OAuth 2.0 Access Token + @access_token = access_token + + # Additional headers to add to each API request + @additional_headers = additional_headers.clone + + # The Http Client to use for making requests. + @http_client = create_http_client + end + + def clone_with(timeout: nil, max_retries: nil, retry_interval: nil, + backoff_factor: nil, environment: nil, access_token: nil, + additional_headers: nil) + timeout ||= self.timeout + max_retries ||= self.max_retries + retry_interval ||= self.retry_interval + backoff_factor ||= self.backoff_factor + environment ||= self.environment + access_token ||= self.access_token + additional_headers ||= self.additional_headers + + Configuration.new(timeout: timeout, max_retries: max_retries, + retry_interval: retry_interval, + backoff_factor: backoff_factor, + environment: environment, access_token: access_token, + additional_headers: additional_headers) + end + + def create_http_client + FaradayClient.new(timeout: timeout, max_retries: max_retries, + retry_interval: retry_interval, + backoff_factor: backoff_factor) + end + + # All the environments the SDK can run in. + @environments = { + 'production' => { + 'default' => 'https://connect.squareup.com' + }, + 'sandbox' => { + 'default' => 'https://connect.squareupsandbox.com' + } + } + + # Generates the appropriate base URI for the environment and the server. + # @param [Configuration::Server] The server enum for which the base URI is + # required. + # @return [String] The base URI. + def get_base_uri(server = 'default') + self.class.environments[environment][server].clone + end + end +end diff --git a/lib/square/exceptions/api_exception.rb b/lib/square/exceptions/api_exception.rb index 7ad44dc7..4c0846b3 100644 --- a/lib/square/exceptions/api_exception.rb +++ b/lib/square/exceptions/api_exception.rb @@ -1,20 +1,20 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # Class for exceptions when there is a network error, status code error, etc. - class APIException < StandardError - attr_reader :response, :response_code - - # The constructor. - # @param [String] The reason for raising an exception. - # @param [HttpResponse] The HttpReponse of the API call. - def initialize(reason, response) - super(reason) - @response = response - @response_code = response.status_code - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # Class for exceptions when there is a network error, status code error, etc. + class APIException < StandardError + attr_reader :response, :response_code + + # The constructor. + # @param [String] The reason for raising an exception. + # @param [HttpResponse] The HttpReponse of the API call. + def initialize(reason, response) + super(reason) + @response = response + @response_code = response.status_code + end + end +end diff --git a/lib/square/http/api_response.rb b/lib/square/http/api_response.rb index f4869894..191be58c 100644 --- a/lib/square/http/api_response.rb +++ b/lib/square/http/api_response.rb @@ -1,50 +1,50 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # Http response received. - class ApiResponse - attr_reader(:status_code, :reason_phrase, :headers, :raw_body, :request, - :data, :errors, :body, :cursor) - - # The constructor - # @param [HttpResponse] The original, raw response from the api. - # @param [Object] The data field specified for the response. - # @param [Array] Any errors returned by the server. - def initialize(http_response, - data: nil, - errors: nil) - @status_code = http_response.status_code - @reason_phrase = http_response.reason_phrase - @headers = http_response.headers - @raw_body = http_response.raw_body - @request = http_response.request - @errors = errors - - if data.is_a? Hash - if data.keys.any? - @body = Struct.new(*data.keys) do - define_method(:to_s) { http_response.raw_body } - end.new(*data.values) - - @cursor = data.fetch(:cursor, nil) - data.reject! { |k| k == :cursor || k == :errors } - @data = Struct.new(*data.keys).new(*data.values) if data.keys.any? - end - else - @data = data - @body = data - end - end - - def success? - status_code >= 200 && status_code < 300 - end - - def error? - status_code >= 400 && status_code < 600 - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # Http response received. + class ApiResponse + attr_reader(:status_code, :reason_phrase, :headers, :raw_body, :request, + :data, :errors, :body, :cursor) + + # The constructor + # @param [HttpResponse] The original, raw response from the api. + # @param [Object] The data field specified for the response. + # @param [Array] Any errors returned by the server. + def initialize(http_response, + data: nil, + errors: nil) + @status_code = http_response.status_code + @reason_phrase = http_response.reason_phrase + @headers = http_response.headers + @raw_body = http_response.raw_body + @request = http_response.request + @errors = errors + + if data.is_a? Hash + if data.keys.any? + @body = Struct.new(*data.keys) do + define_method(:to_s) { http_response.raw_body } + end.new(*data.values) + + @cursor = data.fetch(:cursor, nil) + data.reject! { |k| k == :cursor || k == :errors } + @data = Struct.new(*data.keys).new(*data.values) if data.keys.any? + end + else + @data = data + @body = data + end + end + + def success? + status_code >= 200 && status_code < 300 + end + + def error? + status_code >= 400 && status_code < 600 + end + end +end diff --git a/lib/square/http/auth/o_auth2.rb b/lib/square/http/auth/o_auth2.rb index db9edb34..9f40d885 100644 --- a/lib/square/http/auth/o_auth2.rb +++ b/lib/square/http/auth/o_auth2.rb @@ -1,17 +1,17 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # Utility class for OAuth 2 authorization and token management. - class OAuth2 - # Add OAuth2 authentication to the http request. - # @param [HttpRequest] The HttpRequest object to which authentication will - # be added. - def self.apply(config, http_request) - token = config.access_token - http_request.headers['Authorization'] = "Bearer #{token}" - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # Utility class for OAuth 2 authorization and token management. + class OAuth2 + # Add OAuth2 authentication to the http request. + # @param [HttpRequest] The HttpRequest object to which authentication will + # be added. + def self.apply(config, http_request) + token = config.access_token + http_request.headers['Authorization'] = "Bearer #{token}" + end + end +end diff --git a/lib/square/http/faraday_client.rb b/lib/square/http/faraday_client.rb index ff88f2c3..5c4bb410 100644 --- a/lib/square/http/faraday_client.rb +++ b/lib/square/http/faraday_client.rb @@ -1,64 +1,64 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -require 'faraday/http_cache' -require 'faraday_middleware' - -module Square - # An implementation of HttpClient. - class FaradayClient < HttpClient - # The constructor. - def initialize(timeout:, max_retries:, retry_interval:, - backoff_factor:, cache: false, verify: true) - @connection = Faraday.new do |faraday| - faraday.use Faraday::HttpCache, serializer: Marshal if cache - faraday.use FaradayMiddleware::FollowRedirects - faraday.request :multipart - faraday.request :url_encoded - faraday.ssl[:ca_file] = Certifi.where - faraday.ssl[:verify] = verify - faraday.request :retry, max: max_retries, interval: retry_interval, - backoff_factor: backoff_factor - faraday.adapter Faraday.default_adapter - faraday.options[:params_encoder] = Faraday::FlatParamsEncoder - faraday.options[:timeout] = timeout if timeout > 0 - end - end - - # Method overridden from HttpClient. - def execute_as_string(http_request) - response = @connection.send( - http_request.http_method.downcase, - http_request.query_url - ) do |request| - request.headers = http_request.headers - unless http_request.parameters.empty? - request.body = http_request.parameters - end - end - convert_response(response, http_request) - end - - # Method overridden from HttpClient. - def execute_as_binary(http_request) - response = @connection.send( - http_request.http_method.downcase, - http_request.query_url - ) do |request| - request.headers = http_request.headers - unless http_request.parameters.empty? - request.body = http_request.parameters - end - end - convert_response(response, http_request) - end - - # Method overridden from HttpClient. - def convert_response(response, http_request) - HttpResponse.new(response.status, response.reason_phrase, - response.headers, response.body, http_request) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +require 'faraday/http_cache' +require 'faraday_middleware' + +module Square + # An implementation of HttpClient. + class FaradayClient < HttpClient + # The constructor. + def initialize(timeout:, max_retries:, retry_interval:, + backoff_factor:, cache: false, verify: true) + @connection = Faraday.new do |faraday| + faraday.use Faraday::HttpCache, serializer: Marshal if cache + faraday.use FaradayMiddleware::FollowRedirects + faraday.request :multipart + faraday.request :url_encoded + faraday.ssl[:ca_file] = Certifi.where + faraday.ssl[:verify] = verify + faraday.request :retry, max: max_retries, interval: retry_interval, + backoff_factor: backoff_factor + faraday.adapter Faraday.default_adapter + faraday.options[:params_encoder] = Faraday::FlatParamsEncoder + faraday.options[:timeout] = timeout if timeout > 0 + end + end + + # Method overridden from HttpClient. + def execute_as_string(http_request) + response = @connection.send( + http_request.http_method.downcase, + http_request.query_url + ) do |request| + request.headers = http_request.headers + unless http_request.parameters.empty? + request.body = http_request.parameters + end + end + convert_response(response, http_request) + end + + # Method overridden from HttpClient. + def execute_as_binary(http_request) + response = @connection.send( + http_request.http_method.downcase, + http_request.query_url + ) do |request| + request.headers = http_request.headers + unless http_request.parameters.empty? + request.body = http_request.parameters + end + end + convert_response(response, http_request) + end + + # Method overridden from HttpClient. + def convert_response(response, http_request) + HttpResponse.new(response.status, response.reason_phrase, + response.headers, response.body, http_request) + end + end +end diff --git a/lib/square/http/http_call_back.rb b/lib/square/http/http_call_back.rb index cd740126..4936d72e 100644 --- a/lib/square/http/http_call_back.rb +++ b/lib/square/http/http_call_back.rb @@ -1,24 +1,24 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # HttpCallBack allows defining callables for pre and post API calls. - class HttpCallBack - # A controller will call this method before making an HTTP Request. - # @param [HttpRequest] The HttpRequest object which the HttpClient - # will execute. - def on_before_request(_http_request) - raise NotImplementedError, 'This method needs - to be implemented in a child class.' - end - - # A controller will call this method after making an HTTP Request. - # @param [HttpResponse] The HttpReponse of the API call. - def on_after_response(_http_response) - raise NotImplementedError, 'This method needs - to be implemented in a child class.' - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # HttpCallBack allows defining callables for pre and post API calls. + class HttpCallBack + # A controller will call this method before making an HTTP Request. + # @param [HttpRequest] The HttpRequest object which the HttpClient + # will execute. + def on_before_request(_http_request) + raise NotImplementedError, 'This method needs + to be implemented in a child class.' + end + + # A controller will call this method after making an HTTP Request. + # @param [HttpResponse] The HttpReponse of the API call. + def on_after_response(_http_response) + raise NotImplementedError, 'This method needs + to be implemented in a child class.' + end + end +end diff --git a/lib/square/http/http_client.rb b/lib/square/http/http_client.rb index 068d140b..45047c43 100644 --- a/lib/square/http/http_client.rb +++ b/lib/square/http/http_client.rb @@ -1,104 +1,104 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # An interface for the methods that an HTTP Client must implement. - # - # This class should not be instantiated but should be used as a base class - # for HTTP Client classes. - class HttpClient - # Execute an HttpRequest when the response is expected to be a string. - # @param [HttpRequest] The HttpRequest to be executed. - def execute_as_string(_http_request) - raise NotImplementedError, 'This method needs - to be implemented in a child class.' - end - - # Execute an HttpRequest when the response is expected to be binary. - # @param [HttpRequest] The HttpRequest to be executed. - def execute_as_binary(_http_request) - raise NotImplementedError, 'This method needs - to be implemented in a child class.' - end - - # Converts the HTTP Response from the client to an HttpResponse object. - # @param [Dynamic] The response object received from the client. - def convert_response(_response) - raise NotImplementedError, 'This method needs - to be implemented in a child class.' - end - - # Get a GET HttpRequest object. - # @param [String] The URL to send the request to. - # @param [Hash, Optional] The headers for the HTTP Request. - def get(query_url, - headers: {}) - HttpRequest.new(HttpMethodEnum::GET, - query_url, - headers: headers) - end - - # Get a HEAD HttpRequest object. - # @param [String] The URL to send the request to. - # @param [Hash, Optional] The headers for the HTTP Request. - def head(query_url, - headers: {}) - HttpRequest.new(HttpMethodEnum::HEAD, - query_url, - headers: headers) - end - - # Get a POST HttpRequest object. - # @param [String] The URL to send the request to. - # @param [Hash, Optional] The headers for the HTTP Request. - # @param [Hash, Optional] The parameters for the HTTP Request. - def post(query_url, - headers: {}, - parameters: {}) - HttpRequest.new(HttpMethodEnum::POST, - query_url, - headers: headers, - parameters: parameters) - end - - # Get a PUT HttpRequest object. - # @param [String] The URL to send the request to. - # @param [Hash, Optional] The headers for the HTTP Request. - # @param [Hash, Optional] The parameters for the HTTP Request. - def put(query_url, - headers: {}, - parameters: {}) - HttpRequest.new(HttpMethodEnum::PUT, - query_url, - headers: headers, - parameters: parameters) - end - - # Get a PATCH HttpRequest object. - # @param [String] The URL to send the request to. - # @param [Hash, Optional] The headers for the HTTP Request. - # @param [Hash, Optional] The parameters for the HTTP Request. - def patch(query_url, - headers: {}, - parameters: {}) - HttpRequest.new(HttpMethodEnum::PATCH, - query_url, - headers: headers, - parameters: parameters) - end - - # Get a DELETE HttpRequest object. - # @param [String] The URL to send the request to. - # @param [Hash, Optional] The headers for the HTTP Request. - def delete(query_url, - headers: {}, - parameters: {}) - HttpRequest.new(HttpMethodEnum::DELETE, - query_url, - headers: headers, - parameters: parameters) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # An interface for the methods that an HTTP Client must implement. + # + # This class should not be instantiated but should be used as a base class + # for HTTP Client classes. + class HttpClient + # Execute an HttpRequest when the response is expected to be a string. + # @param [HttpRequest] The HttpRequest to be executed. + def execute_as_string(_http_request) + raise NotImplementedError, 'This method needs + to be implemented in a child class.' + end + + # Execute an HttpRequest when the response is expected to be binary. + # @param [HttpRequest] The HttpRequest to be executed. + def execute_as_binary(_http_request) + raise NotImplementedError, 'This method needs + to be implemented in a child class.' + end + + # Converts the HTTP Response from the client to an HttpResponse object. + # @param [Dynamic] The response object received from the client. + def convert_response(_response) + raise NotImplementedError, 'This method needs + to be implemented in a child class.' + end + + # Get a GET HttpRequest object. + # @param [String] The URL to send the request to. + # @param [Hash, Optional] The headers for the HTTP Request. + def get(query_url, + headers: {}) + HttpRequest.new(HttpMethodEnum::GET, + query_url, + headers: headers) + end + + # Get a HEAD HttpRequest object. + # @param [String] The URL to send the request to. + # @param [Hash, Optional] The headers for the HTTP Request. + def head(query_url, + headers: {}) + HttpRequest.new(HttpMethodEnum::HEAD, + query_url, + headers: headers) + end + + # Get a POST HttpRequest object. + # @param [String] The URL to send the request to. + # @param [Hash, Optional] The headers for the HTTP Request. + # @param [Hash, Optional] The parameters for the HTTP Request. + def post(query_url, + headers: {}, + parameters: {}) + HttpRequest.new(HttpMethodEnum::POST, + query_url, + headers: headers, + parameters: parameters) + end + + # Get a PUT HttpRequest object. + # @param [String] The URL to send the request to. + # @param [Hash, Optional] The headers for the HTTP Request. + # @param [Hash, Optional] The parameters for the HTTP Request. + def put(query_url, + headers: {}, + parameters: {}) + HttpRequest.new(HttpMethodEnum::PUT, + query_url, + headers: headers, + parameters: parameters) + end + + # Get a PATCH HttpRequest object. + # @param [String] The URL to send the request to. + # @param [Hash, Optional] The headers for the HTTP Request. + # @param [Hash, Optional] The parameters for the HTTP Request. + def patch(query_url, + headers: {}, + parameters: {}) + HttpRequest.new(HttpMethodEnum::PATCH, + query_url, + headers: headers, + parameters: parameters) + end + + # Get a DELETE HttpRequest object. + # @param [String] The URL to send the request to. + # @param [Hash, Optional] The headers for the HTTP Request. + def delete(query_url, + headers: {}, + parameters: {}) + HttpRequest.new(HttpMethodEnum::DELETE, + query_url, + headers: headers, + parameters: parameters) + end + end +end diff --git a/lib/square/http/http_method_enum.rb b/lib/square/http/http_method_enum.rb index c78d1de7..29ef31d2 100644 --- a/lib/square/http/http_method_enum.rb +++ b/lib/square/http/http_method_enum.rb @@ -1,13 +1,13 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # HTTP Methods Enumeration. - class HttpMethodEnum - HTTPMETHODENUM = [GET = 'GET'.freeze, POST = 'POST'.freeze, - PUT = 'PUT'.freeze, PATCH = 'PATCH'.freeze, - DELETE = 'DELETE'.freeze, HEAD = 'HEAD'.freeze].freeze - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # HTTP Methods Enumeration. + class HttpMethodEnum + HTTPMETHODENUM = [GET = 'GET'.freeze, POST = 'POST'.freeze, + PUT = 'PUT'.freeze, PATCH = 'PATCH'.freeze, + DELETE = 'DELETE'.freeze, HEAD = 'HEAD'.freeze].freeze + end +end diff --git a/lib/square/http/http_request.rb b/lib/square/http/http_request.rb index 40634e58..65aeb9d9 100644 --- a/lib/square/http/http_request.rb +++ b/lib/square/http/http_request.rb @@ -1,50 +1,50 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # Represents a single Http Request. - class HttpRequest - attr_accessor :http_method, :query_url, :headers, - :parameters, :username, :password - - # The constructor. - # @param [HttpMethodEnum] The HTTP method. - # @param [String] The URL to send the request to. - # @param [Hash, Optional] The headers for the HTTP Request. - # @param [Hash, Optional] The parameters for the HTTP Request. - def initialize(http_method, - query_url, - headers: {}, - parameters: {}) - @http_method = http_method - @query_url = query_url - @headers = headers - @parameters = parameters - end - - # Add a header to the HttpRequest. - # @param [String] The name of the header. - # @param [String] The value of the header. - def add_header(name, value) - @headers[name] = value - end - - # Add a parameter to the HttpRequest. - # @param [String] The name of the parameter. - # @param [String] The value of the parameter. - def add_parameter(name, value) - @parameters[name] = value - end - - # Add a query parameter to the HttpRequest. - # @param [String] The name of the query parameter. - # @param [String] The value of the query parameter. - def add_query_parameter(name, value) - @query_url = APIHelper.append_url_with_query_parameters(@query_url, - name => value) - @query_url = APIHelper.clean_url(@query_url) - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # Represents a single Http Request. + class HttpRequest + attr_accessor :http_method, :query_url, :headers, + :parameters, :username, :password + + # The constructor. + # @param [HttpMethodEnum] The HTTP method. + # @param [String] The URL to send the request to. + # @param [Hash, Optional] The headers for the HTTP Request. + # @param [Hash, Optional] The parameters for the HTTP Request. + def initialize(http_method, + query_url, + headers: {}, + parameters: {}) + @http_method = http_method + @query_url = query_url + @headers = headers + @parameters = parameters + end + + # Add a header to the HttpRequest. + # @param [String] The name of the header. + # @param [String] The value of the header. + def add_header(name, value) + @headers[name] = value + end + + # Add a parameter to the HttpRequest. + # @param [String] The name of the parameter. + # @param [String] The value of the parameter. + def add_parameter(name, value) + @parameters[name] = value + end + + # Add a query parameter to the HttpRequest. + # @param [String] The name of the query parameter. + # @param [String] The value of the query parameter. + def add_query_parameter(name, value) + @query_url = APIHelper.append_url_with_query_parameters(@query_url, + name => value) + @query_url = APIHelper.clean_url(@query_url) + end + end +end diff --git a/lib/square/http/http_response.rb b/lib/square/http/http_response.rb index e73fe1bd..260078ac 100644 --- a/lib/square/http/http_response.rb +++ b/lib/square/http/http_response.rb @@ -1,29 +1,29 @@ -# square -# -# This file was automatically generated by APIMATIC v2.0 -# ( https://apimatic.io ). - -module Square - # Http response received. - class HttpResponse - attr_reader :status_code, :reason_phrase, :headers, :raw_body, :request - - # The constructor - # @param [Integer] The status code returned by the server. - # @param [String] The reason phrase returned by the server. - # @param [Hash] The headers sent by the server in the response. - # @param [String] The raw body of the response. - # @param [HttpRequest] The request that resulted in this response. - def initialize(status_code, - reason_phrase, - headers, - raw_body, - request) - @status_code = status_code - @reason_phrase = reason_phrase - @headers = headers - @raw_body = raw_body - @request = request - end - end -end +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +module Square + # Http response received. + class HttpResponse + attr_reader :status_code, :reason_phrase, :headers, :raw_body, :request + + # The constructor + # @param [Integer] The status code returned by the server. + # @param [String] The reason phrase returned by the server. + # @param [Hash] The headers sent by the server in the response. + # @param [String] The raw body of the response. + # @param [HttpRequest] The request that resulted in this response. + def initialize(status_code, + reason_phrase, + headers, + raw_body, + request) + @status_code = status_code + @reason_phrase = reason_phrase + @headers = headers + @raw_body = raw_body + @request = request + end + end +end diff --git a/test/api/test_labor_api.rb b/test/api/test_labor_api.rb new file mode 100644 index 00000000..ec169666 --- /dev/null +++ b/test/api/test_labor_api.rb @@ -0,0 +1,74 @@ +# square +# +# This file was automatically generated by APIMATIC v2.0 +# ( https://apimatic.io ). + +require_relative 'api_test_base' + +class LaborApiTests < ApiTestBase + # Called only once for the class before any test has executed + def setup + @response_catcher = HttpResponseCatcher.new + @controller = LaborApi.new CONFIG, http_call_back: @response_catcher + end + + # Returns a paginated list of `BreakType` instances for a business. + def test_list_break_types() + # Parameters for the API call + location_id = nil + limit = nil + cursor = nil + + # Perform the API call through the SDK function + result = @controller.list_break_types(location_id: location_id, limit: limit, cursor: cursor) + + # Test response code + assert_equal(200, @response_catcher.response.status_code) + + # Test headers + expected_headers = {} + expected_headers['content-type'] = 'application/json' + + assert(TestHelper.match_headers(expected_headers, @response_catcher.response.headers)) + end + + # Returns a paginated list of `EmployeeWage` instances for a business. + def test_list_employee_wages() + # Parameters for the API call + employee_id = nil + limit = nil + cursor = nil + + # Perform the API call through the SDK function + result = @controller.list_employee_wages(employee_id: employee_id, limit: limit, cursor: cursor) + + # Test response code + assert_equal(200, @response_catcher.response.status_code) + + # Test headers + expected_headers = {} + expected_headers['content-type'] = 'application/json' + + assert(TestHelper.match_headers(expected_headers, @response_catcher.response.headers)) + end + + # Returns a list of `WorkweekConfig` instances for a business. + def test_list_workweek_configs() + # Parameters for the API call + limit = nil + cursor = nil + + # Perform the API call through the SDK function + result = @controller.list_workweek_configs(limit: limit, cursor: cursor) + + # Test response code + assert_equal(200, @response_catcher.response.status_code) + + # Test headers + expected_headers = {} + expected_headers['content-type'] = 'application/json' + + assert(TestHelper.match_headers(expected_headers, @response_catcher.response.headers)) + end + +end