Icon

Square (version v1.*.*)

adjust_inventory

Adjusts an item variation's current available inventory.

Parameters

location_id (required)

The ID of the item's associated location.

Type: string

variation_id (required)

The ID of the variation to adjust inventory information for.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"quantity_delta" : "The number to adjust the variation's quantity by.",
"adjustment_type" : "The reason for the inventory adjustment. See [V1AdjustInventoryRequestAdjustmentType](#type-v1adjustinventoryrequestadjustmenttype) for possible values",
"memo" : "A note about the inventory adjustment."
}

apply_fee

Associates a fee with an item, meaning the fee is automatically applied to the item in Square Register.

Parameters

fee_id (required)

The ID of the fee to apply.

Type: string

item_id (required)

The ID of the item to add the fee to.

Type: string

location_id (required)

The ID of the fee's associated location.

Type: string

apply_modifier_list

Associates a modifier list with an item, meaning modifier options from the list can be applied to the item.

Parameters

item_id (required)

The ID of the item to add the modifier list to.

Type: string

location_id (required)

The ID of the item's associated location.

Type: string

modifier_list_id (required)

The ID of the modifier list to apply.

Type: string

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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"changes" : [ {
"transfer" : {
"from_location_id" : "The Square ID of the [Location](#type-location) where the related\nquantity of items were tracked before the transfer.",
"occurred_at" : "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.",
"catalog_object_id" : "The Square generated ID of the\n[CatalogObject](#type-catalogobject) being tracked.",
"catalog_object_type" : "The [CatalogObjectType](#type-catalogobjecttype) of the\n[CatalogObject](#type-catalogobject) being tracked.Tracking is only\nsupported for the `ITEM_VARIATION` type.",
"quantity" : "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)](/orders-api/what-it-does#decimal-quantities) for more information.",
"reference_id" : "An optional ID provided by the application to tie the\n[InventoryTransfer](#type-inventorytransfer) to an external system.",
"to_location_id" : "The Square ID of the [Location](#type-location) where the related\nquantity of items were tracked after the transfer.",
"employee_id" : "The Square ID of the [Employee](#type-employee) responsible for the\ninventory transfer.",
"created_at" : "A read-only timestamp in RFC 3339 format that indicates when Square\nreceived the transfer request.",
"id" : "A unique ID generated by Square for the\n[InventoryTransfer](#type-inventorytransfer).",
"state" : "The [InventoryState](#type-inventorystate) for the quantity of\nitems being transfered.\nSee [InventoryState](#type-inventorystate) for possible values",
"source" : {
"product" : "Read-only [Product](#type-product) type for the application.\nSee [Product](#type-product) for possible values",
"name" : "Read-only display name assigned to the application\n(e.g. `\"Custom Application\"`, `\"Square POS 4.74 for Android\"`).",
"application_id" : "Read-only Square ID assigned to the application. Only used for\n[Product](#type-product) type `EXTERNAL_API`."
}
},
"physical_count" : {
"occurred_at" : "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.",
"catalog_object_id" : "The Square generated ID of the\n[CatalogObject](#type-catalogobject) being tracked.",
"catalog_object_type" : "The [CatalogObjectType](#type-catalogobjecttype) of the\n[CatalogObject](#type-catalogobject) being tracked. Tracking is only\nsupported for the `ITEM_VARIATION` type.",
"quantity" : "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)](/orders-api/what-it-does#decimal-quantities) for more information.",
"reference_id" : "An optional ID provided by the application to tie the [InventoryPhysicalCount](#type-inventoryphysicalcount) to an external system.",
"employee_id" : "The Square ID of the [Employee](#type-employee) responsible for the\nphysical count.",
"created_at" : "A read-only timestamp in RFC 3339 format that indicates when Square\nreceived the physical count.",
"id" : "A unique ID generated by Square for the\n[InventoryPhysicalCount](#type-inventoryphysicalcount).",
"state" : "The current [InventoryState](#type-inventorystate) for the related\nquantity of items.\nSee [InventoryState](#type-inventorystate) for possible values",
"source" : {
"product" : "Read-only [Product](#type-product) type for the application.\nSee [Product](#type-product) for possible values",
"name" : "Read-only display name assigned to the application\n(e.g. `\"Custom Application\"`, `\"Square POS 4.74 for Android\"`).",
"application_id" : "Read-only Square ID assigned to the application. Only used for\n[Product](#type-product) type `EXTERNAL_API`."
},
"location_id" : "The Square ID of the [Location](#type-location) where the related\nquantity of items are being tracked."
},
"adjustment" : {
"transaction_id" : "The read-only Square ID of the [Transaction][#type-transaction] that\ncaused the adjustment. Only relevant for payment-related state\ntransitions.",
"catalog_object_id" : "The Square generated ID of the\n[CatalogObject](#type-catalogobject) being tracked.",
"total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"quantity" : "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)](/orders-api/what-it-does#decimal-quantities) for more information.",
"reference_id" : "An optional ID provided by the application to tie the\n[InventoryAdjustment](#type-inventoryadjustment) to an external\nsystem.",
"purchase_order_id" : "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" : "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.",
"created_at" : "A read-only timestamp in RFC 3339 format that indicates when Square\nreceived the adjustment.",
"source" : {
"product" : "Read-only [Product](#type-product) type for the application.\nSee [Product](#type-product) for possible values",
"name" : "Read-only display name assigned to the application\n(e.g. `\"Custom Application\"`, `\"Square POS 4.74 for Android\"`).",
"application_id" : "Read-only Square ID assigned to the application. Only used for\n[Product](#type-product) type `EXTERNAL_API`."
},
"refund_id" : "The read-only Square ID of the [Refund][#type-refund] that\ncaused the adjustment. Only relevant for refund-related state\ntransitions.",
"to_state" : "The [InventoryState](#type-inventorystate) of the related quantity\nof items after the adjustment.\nSee [InventoryState](#type-inventorystate) for possible values",
"location_id" : "The Square ID of the [Location](#type-location) where the related\nquantity of items are being tracked.",
"occurred_at" : "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.",
"from_state" : "The [InventoryState](#type-inventorystate) of the related quantity\nof items before the adjustment.\nSee [InventoryState](#type-inventorystate) for possible values",
"catalog_object_type" : "The [CatalogObjectType](#type-catalogobjecttype) of the\n[CatalogObject](#type-catalogobject) being tracked. Tracking is only\nsupported for the `ITEM_VARIATION` type.",
"employee_id" : "The Square ID of the [Employee](#type-employee) responsible for the\ninventory adjustment.",
"id" : "A unique ID generated by Square for the\n[InventoryAdjustment](#type-inventoryadjustment)."
},
"type" : "Indicates how the inventory change was applied. See [InventoryChangeType](#type-inventorychangetype) for possible values"
} ],
"ignore_unchanged_counts" : "Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: `true`.",
"idempotency_key" : "A client-supplied, universally unique identifier (UUID) for the\nrequest.\nSee [Idempotency](/basics/api101/idempotency) in the\n[API Development 101](/basics/api101/overview) section for more\ninformation."
}

batch_delete_catalog_objects

Deletes a set of CatalogItems 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 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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"object_ids" : [ "string" ]
}

batch_retrieve_catalog_objects

Returns a set of objects based on the provided ID. Each CatalogItem returned in the set includes all of its child information including: all of its CatalogItemVariation objects, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"object_ids" : [ "string" ],
"include_related_objects" : "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."
}

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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"updated_before" : "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" : "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.",
"types" : [ "string" ],
"location_ids" : [ "string" ],
"updated_after" : "Provided as an RFC 3339 timestamp. Returns results whose\n`created_at` or `calculated_at` value is after the given time.\nDefault: UNIX epoch (`1970-01-01T00:00:00Z`).",
"catalog_object_ids" : [ "string" ],
"states" : [ "string" ]
}

batch_retrieve_inventory_counts

Returns current counts for the provided CatalogObjects at the requested Locations. 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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"cursor" : "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_ids" : [ "string" ],
"updated_after" : "Provided as an RFC 3339 timestamp. Returns results whose\n`calculated_at` value is after the given time. Default: UNIX epoch\n(`1970-01-01T00:00:00Z`).",
"catalog_object_ids" : [ "string" ]
}

batch_retrieve_orders

Retrieves a set of Orders by their IDs. If a given Order ID does not exist, the ID is ignored instead of generating an error.

Parameters

location_id (required)

The ID of the orders' associated location.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"order_ids" : [ "string" ]
}

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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"batches" : [ {
"objects" : [ {
"category_data" : {
"name" : "The category's name. Searchable. This field has max length of 255 Unicode code points."
},
"measurement_unit_data" : {
"precision" : "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",
"measurement_unit" : {
"volume_unit" : "Represents a standard volume unit. See [MeasurementUnitVolume](#type-measurementunitvolume) for possible values",
"weight_unit" : "Represents a standard unit of weight or mass. See [MeasurementUnitWeight](#type-measurementunitweight) for possible values",
"generic_unit" : "Reserved for API integrations that lack the ability to specify a real measurement unit See [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values",
"area_unit" : "Represents a standard area unit. See [MeasurementUnitArea](#type-measurementunitarea) for possible values",
"type" : "Represents the type of the measurement unit. See [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values",
"custom_unit" : {
"name" : "The name of the custom unit, for example \"bushel\".",
"abbreviation" : "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears in the cart for the Point of Sale app, and in reports."
},
"length_unit" : "Represents a standard length unit. See [MeasurementUnitLength](#type-measurementunitlength) for possible values"
}
},
"discount_data" : {
"pin_required" : "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" : "The color of the discount's display label in the Square Point of Sale app. This must be a valid hex color code.",
"percentage" : "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.",
"name" : "The discount's name. Searchable. This field has max length of 255 Unicode code points.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"discount_type" : "Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale. See [CatalogDiscountType](#type-catalogdiscounttype) for possible values"
},
"item_option_value_data" : {
"item_option_id" : "Unique ID of the associated item option.",
"color" : "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.",
"name" : "Name of this item option value. Searchable.",
"description" : "The option value's human-readable description.",
"item_variation_count" : "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.",
"ordinal" : "Determines where this option value appears in a list of option values."
},
"catalog_v1_ids" : [ {
"location_id" : "The ID of the [location](#type-location) this Connect V1 ID is associated with.",
"catalog_v1_id" : "The ID for an object in Connect V1, if different from its Connect V2 ID."
} ],
"absent_at_location_ids" : [ "string" ],
"modifier_list_data" : {
"selection_type" : "Indicates whether multiple options from the [CatalogModifierList](#type-catalogmodifierlist) can be applied to a single [CatalogItem](#type-catalogitem). See [CatalogModifierListSelectionType](#type-catalogmodifierlistselectiontype) for possible values",
"name" : "The [CatalogModifierList](#type-catalogmodifierlist)'s name. Searchable. This field has max length of 255 Unicode code points.",
"modifiers" : [ "CatalogObject" ]
},
"type" : "The type of this object. Each object type has expected properties expressed in a structured format within its corresponding `*_data` field below. See [CatalogObjectType](#type-catalogobjecttype) for possible values",
"version" : "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.",
"present_at_location_ids" : [ "string" ],
"tax_data" : {
"calculation_phase" : "Whether the tax is calculated based on a payment's subtotal or total. See [TaxCalculationPhase](#type-taxcalculationphase) for possible values",
"percentage" : "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%.",
"name" : "The tax's name. Searchable. This field has max length of 255 Unicode code points.",
"inclusion_type" : "Whether the tax is `ADDITIVE` or `INCLUSIVE`.\nSee [TaxInclusionType](#type-taxinclusiontype) for possible values",
"applies_to_custom_amounts" : "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" : "If `true`, the tax will be shown as enabled in the Square Point of Sale app."
},
"item_data" : {
"item_options" : [ {
"item_option_id" : "The unique id of the item option, used to form the dimensions of the item option matrix in a specified order."
} ],
"tax_ids" : [ "string" ],
"label_color" : "The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code.",
"description" : "The item's description. Searchable. This field has max length of 4096 Unicode code points.",
"modifier_list_info" : [ {
"max_selected_modifiers" : "If zero or larger, the largest number of [CatalogModifier](#type-catalogmodifier)s that can be selected from this [CatalogModifierList](#type-catalogmodifierlist).",
"modifier_list_id" : "The ID of the [CatalogModifierList](#type-catalogmodifierlist) controlled by this [CatalogModifierListInfo](#type-catalogmodifierlistinfo).",
"modifier_overrides" : [ {
"on_by_default" : "If `true`, this [CatalogModifier](#type-catalogmodifier) should be selected by default for this [CatalogItem](#type-catalogitem).",
"modifier_id" : "The ID of the [CatalogModifier](#type-catalogmodifier) whose default behavior is being overridden."
} ],
"enabled" : "If `true`, enable this [CatalogModifierList](#type-catalogmodifierlist).",
"min_selected_modifiers" : "If zero or larger, the smallest number of [CatalogModifier](#type-catalogmodifier)s that must be selected from this [CatalogModifierList](#type-catalogmodifierlist)."
} ],
"abbreviation" : "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.",
"available_electronically" : "If `true`, the item can be added to electronically fulfilled orders from the merchant's online store.",
"product_type" : "The product type of the item. May not be changed once an item has been created. Only items of product type `REGULAR` or `APPOINTMENTS_SERVICE` may be created by this API; items with other product types are read-only. See [CatalogItemProductType](#type-catalogitemproducttype) for possible values",
"category_id" : "The ID of the item's category, if any.",
"variations" : [ "CatalogObject" ],
"name" : "The item's name. Searchable. This field must not be empty. This field has max length of 512 Unicode code points.",
"skip_modifier_screen" : "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.",
"available_online" : "If `true`, the item can be added to shipping orders from the merchant's online store.",
"available_for_pickup" : "If `true`, the item can be added to pickup orders from the merchant's online store."
},
"present_at_all_locations" : "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`.",
"product_set_data" : {
"product_ids_all" : [ "string" ],
"all_products" : "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.",
"quantity_min" : "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.",
"name" : "User-defined name for the product set. For example, \"Clearance Items\"\nor \"Winter Sale Items\".",
"quantity_exact" : "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_max" : "If set, the pricing rule will apply to a maximum of this many items from `products_any` or `products_all`.",
"product_ids_any" : [ "string" ]
},
"is_deleted" : "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.",
"updated_at" : "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.",
"item_variation_data" : {
"item_option_values" : [ {
"item_option_id" : "The unique id of an item option.",
"item_option_value_id" : "The unique id of the selected value for the item option."
} ],
"price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"item_id" : "The ID of the [CatalogItem](#type-catalogitem) associated with this item variation. Searchable.",
"upc" : "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.",
"location_overrides" : [ {
"pricing_type" : "The pricing type (fixed or variable) for the [CatalogItemVariation](#type-catalogitemvariation) at the given [location](#type-location). See [CatalogPricingType](#type-catalogpricingtype) for possible values",
"price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"inventory_alert_threshold" : "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.",
"track_inventory" : "If `true`, inventory tracking is active for the [CatalogItemVariation](#type-catalogitemvariation) at this [location](#type-location).",
"location_id" : "The ID of the [location](#type-location).",
"inventory_alert_type" : "Indicates whether the [CatalogItemVariation](#type-catalogitemvariation) displays an alert when its inventory quantity is less than or equal to its `inventory_alert_threshold`. See [InventoryAlertType](#type-inventoryalerttype) for possible values"
} ],
"user_data" : "Arbitrary user metadata to associate with the item variation. Cannot exceed 255 characters. Searchable.",
"service_duration" : "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).",
"pricing_type" : "Indicates whether the item variation's price is fixed or determined at the time of sale. See [CatalogPricingType](#type-catalogpricingtype) for possible values",
"inventory_alert_threshold" : "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.",
"measurement_unit_id" : "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.",
"name" : "The item variation's name. Searchable. This field has max length of 255 Unicode code points.",
"track_inventory" : "If `true`, inventory tracking is active for the variation.",
"sku" : "The item variation's SKU, if any. Searchable.",
"ordinal" : "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.",
"inventory_alert_type" : "Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its `inventory_alert_threshold`. See [InventoryAlertType](#type-inventoryalerttype) for possible values"
},
"time_period_data" : {
"event" : "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."
},
"image_data" : {
"name" : "The internal name of this image. Identifies this image in calls to the Connect APIs.",
"caption" : "A caption that describes what is shown in the image. Displayed in the Square Online Store.",
"url" : "The URL of this image. Generated by Square after an image is uploaded to the CreateCatalogImage endpoint."
},
"item_option_data" : {
"item_count" : "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`.",
"values" : [ "CatalogObject" ],
"name" : "The item option's display name for the seller. Must be unique across\nall item options. Searchable.",
"description" : "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" : "If true, display colors for entries in `values` when present.",
"display_name" : "The item option's display name for the customer. Searchable."
},
"id" : "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.",
"image_id" : "Identifies the `CatalogImage` attached to this `CatalogObject`.",
"pricing_rule_data" : {
"time_period_ids" : [ "string" ],
"exclude_products_id" : "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_until_date" : "Represents the date the pricing rule will become inactive.\nRepresented in RFC3339 full-date format (YYYY-MM-DD).",
"name" : "User-defined name for the pricing rule. For example, \"Buy one get one free\" or \"10% off\".",
"apply_products_id" : "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.",
"match_products_id" : "Unique ID for the [CatalogProductSet](#type-catalogproductset) that will be matched by this rule. A match rule matches within the entire cart.",
"valid_from_date" : "Represents the date the Pricing Rule is valid from. Represented in\nRFC3339 full-date format (YYYY-MM-DD).",
"valid_from_local_time" : "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_local_time" : "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.",
"discount_id" : "Unique ID for the [CatalogDiscount](#type-catalogdiscount) to take off the price of all matched items. Only one of `total_price_money`, `item_price`, or `discount` can be supplied."
},
"modifier_data" : {
"price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The modifier's name. Searchable. This field has max length of 255 Unicode code points."
}
} ]
} ],
"idempotency_key" : "A value you specify that uniquely identifies this\nrequest among all your requests. A common way to create\na valid idempotency key is to use a Universally unique\nidentifier (UUID).\nIf you're unsure whether a particular request was successful,\nyou can reattempt it with the same idempotency key without\nworrying about creating duplicate objects.\nSee [Idempotency](/basics/api101/idempotency) for more information."
}

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.

Parameters

payment_id (required)

payment_id identifying the payment to be canceled.

Type: string

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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"idempotency_key" : "`idempotency_key` identifying the payment to be canceled."
}

catalog_info

This operation has no parameters

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.

Parameters

payment_id (required)

Unique ID identifying the payment to be completed.

Type: string

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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"idempotency_key" : "Unique string value to insure idempotency of the operation",
"break_type" : {
"updated_at" : "A read-only timestamp in RFC 3339 format.",
"break_name" : "A human-readable name for this type of break. Will be displayed to\nemployees in Square products.",
"expected_duration" : "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthis break. Precision below minutes is truncated.",
"created_at" : "A read-only timestamp in RFC 3339 format.",
"id" : "UUID for this object.",
"is_paid" : "Whether this break counts towards time worked for compensation\npurposes.",
"version" : "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.",
"location_id" : "The ID of the business location this type of break applies to."
}
}

create_category

Creates an item category.

Parameters

location_id (required)

The ID of the location to create an item for.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"name" : "The category's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The category's unique ID."
}

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.

Parameters

location_id (required)

The ID of the business location to associate the checkout with.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"note" : "An optional note to associate with the checkout object.\nThis value cannot exceed 60 characters.",
"merchant_support_email" : "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.",
"ask_for_shipping_address" : "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`.",
"pre_populate_shipping_address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"idempotency_key" : "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](/basics/api101/idempotency) for more information.",
"additional_recipients" : [ {
"description" : "The description of the additional recipient.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"location_id" : "The location ID for a recipient (other than the merchant) receiving a portion of the tender."
} ],
"pre_populate_buyer_email" : "If provided, the buyer's email is pre-populated on the checkout page\nas an editable text field.\nDefault: none; only exists if explicitly set.",
"redirect_url" : "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.",
"order" : {
"idempotency_key" : "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](/basics/api101/idempotency) for more information.",
"order" : {
"reference_id" : "A client specified identifier to associate an entity in another system with this order.",
"taxes" : [ {
"uid" : "Unique ID that identifies the tax only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogTax](#type-catalogtax).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"percentage" : "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%.",
"scope" : "Indicates the level at which the tax applies. For `ORDER` scoped taxes, Square generates references in `applied_taxes` on all order line items that do not have them. For `LINE_ITEM` scoped taxes, the tax will only apply to line items with references in their `applied_taxes` field. This field is immutable. To change the scope, you must delete the tax and re-add it as a new tax. See [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values",
"name" : "The tax's name.",
"type" : "Indicates the calculation method used to apply the tax. See [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values"
} ],
"created_at" : "Timestamp for when the order was created. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\".",
"source" : {
"name" : "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."
},
"line_items" : [ {
"quantity_unit" : {
"precision" : "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.",
"measurement_unit" : {
"volume_unit" : "Represents a standard volume unit. See [MeasurementUnitVolume](#type-measurementunitvolume) for possible values",
"weight_unit" : "Represents a standard unit of weight or mass. See [MeasurementUnitWeight](#type-measurementunitweight) for possible values",
"generic_unit" : "Reserved for API integrations that lack the ability to specify a real measurement unit See [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values",
"area_unit" : "Represents a standard area unit. See [MeasurementUnitArea](#type-measurementunitarea) for possible values",
"type" : "Represents the type of the measurement unit. See [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values",
"custom_unit" : {
"name" : "The name of the custom unit, for example \"bushel\".",
"abbreviation" : "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears in the cart for the Point of Sale app, and in reports."
},
"length_unit" : "Represents a standard length unit. See [MeasurementUnitLength](#type-measurementunitlength) for possible values"
}
},
"note" : "The note of the line item.",
"catalog_object_id" : "The [CatalogItemVariation](#type-catalogitemvariation) id applied to this line item.",
"quantity" : "The quantity purchased, formatted as a decimal number.\nFor example: `\"3\"`.\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example: `\"1.70000\"`.",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"variation_name" : "The name of the variation applied to this line item.",
"modifiers" : [ {
"uid" : "Unique ID that identifies the modifier only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogModifier](#type-catalogmodifier).",
"total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The name of the item modifier."
} ],
"gross_sales_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"uid" : "Unique ID that identifies the line item only within this order.",
"variation_total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The name of the line item.",
"total_discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ],
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_discounts" : [ {
"uid" : "Unique ID that identifies the applied discount only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"discount_uid" : "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`."
} ]
} ],
"location_id" : "The ID of the merchant location this order is associated with.",
"refunds" : [ {
"transaction_id" : "The ID of the transaction that the refunded tender is part of.",
"reason" : "The reason for the refund being issued.",
"tender_id" : "The ID of the refunded tender.",
"created_at" : "The time when the refund was created, in RFC 3339 format.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"id" : "The refund's unique ID.",
"processing_fee_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"additional_recipients" : [ {
"receivable_id" : "The unique ID for this [AdditionalRecipientReceivable](#type-additionalrecipientreceivable), assigned by the server.",
"description" : "The description of the additional recipient.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"location_id" : "The location ID for a recipient (other than the merchant) receiving a portion of this tender."
} ],
"location_id" : "The ID of the refund's associated location.",
"status" : "The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`,\nor `FAILED`).\nSee [RefundStatus](#type-refundstatus) for possible values"
} ],
"fulfillments" : [ {
"uid" : "Unique ID that identifies the fulfillment only within this order.",
"pickup_details" : {
"note" : "A note meant to provide additional instructions about the pickup fulfillment displayed in the Square Point of Sale and set by the API.",
"schedule_type" : "The schedule type of the pickup fulfillment. Defaults to `SCHEDULED`. See [OrderFulfillmentPickupDetailsScheduleType](#type-orderfulfillmentpickupdetailsscheduletype) for possible values",
"rejected_at" : "The [timestamp](#workingwithdates) indicating when the fulfillment was rejected. In RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"pickup_at" : "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.",
"canceled_at" : "The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\", indicating when the fulfillment was canceled.",
"pickup_window_duration" : "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.",
"expired_at" : "The [timestamp](#workingwithdates) indicating when the fulfillment expired. In RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"placed_at" : "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" : "The [timestamp](#workingwithdates) indicating when the fulfillment\nwas accepted. In RFC3339 timestamp format,\ne.g., \"2016-09-04T23:59:33.123Z\".",
"cancel_reason" : "A description of why the pickup was canceled. Max length: 100 characters.",
"expires_at" : "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.",
"ready_at" : "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\".",
"picked_up_at" : "The [timestamp](#workingwithdates) indicating when the fulfillment\nwas picked up by the recipient. In RFC3339 timestamp format,\ne.g., \"2016-09-04T23:59:33.123Z\".",
"recipient" : {
"email_address" : "The email address of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"phone_number" : "The phone number of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"customer_id" : "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" : "The display name of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`."
},
"auto_complete_duration" : "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.",
"prep_time_duration" : "The duration of time it takes to prepare this fulfillment.\nMust be in RFC3339 duration format, e.g., \"P1W3D\"."
},
"shipment_details" : {
"packaged_at" : "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\".",
"shipped_at" : "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\".",
"shipping_note" : "A note with additional information for the shipping carrier.",
"expected_shipped_at" : "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\".",
"canceled_at" : "The [timestamp](#workingwithdates) indicating the shipment was canceled. Must be in RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"shipping_type" : "A description of the type of shipping product purchased from the carrier. e.g. First Class, Priority, Express",
"in_progress_at" : "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\".",
"failure_reason" : "A description of why the shipment failed to be completed.",
"placed_at" : "The [timestamp](#workingwithdates) indicating when the shipment was requested. Must be in RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"carrier" : "The shipping carrier being used to ship this fulfillment\ne.g. UPS, FedEx, USPS, etc.",
"cancel_reason" : "A description of why the shipment was canceled.",
"recipient" : {
"email_address" : "The email address of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"phone_number" : "The phone number of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"customer_id" : "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" : "The display name of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`."
},
"tracking_number" : "The reference number provided by the carrier to track the shipment's progress.",
"failed_at" : "The [timestamp](#workingwithdates) indicating when the shipment\nfailed to be completed. Must be in RFC3339 timestamp format, e.g.,\n\"2016-09-04T23:59:33.123Z\".",
"tracking_url" : "A link to the tracking webpage on the carrier's website."
},
"state" : "The state of the fulfillment. See [OrderFulfillmentState](#type-orderfulfillmentstate) for possible values",
"type" : "The type of the fulfillment. See [OrderFulfillmentType](#type-orderfulfillmenttype) for possible values"
} ],
"discounts" : [ {
"uid" : "Unique ID that identifies the discount only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogDiscount](#type-catalogdiscount).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"percentage" : "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.",
"scope" : "Indicates the level at which the discount applies. For `ORDER` scoped discounts, Square generates references in `applied_discounts` on all order line items that do not have them. For `LINE_ITEM` scoped discounts, the discount only applies to line items with a discount reference in their `applied_discounts` field. This field is immutable. To change the scope of a discount you must delete the discount and re-add it as a new discount. See [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values",
"name" : "The discount's name.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"type" : "The type of the discount. If it is created by API, it would be either `FIXED_PERCENTAGE` or `FIXED_AMOUNT`. VARIABLE_* is not supported in API because the order is created at the time of sale and either percentage or amount has to be specified. See [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values"
} ],
"updated_at" : "Timestamp for when the order was last updated. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\".",
"total_discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"net_amounts" : {
"discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"id" : "The order's unique ID.",
"state" : "The current state of the order. `OPEN`,`COMPLETED`,`CANCELED`\nSee [OrderState](#type-orderstate) for possible values",
"rounding_adjustment" : {
"uid" : "Unique ID that identifies the rounding adjustment only within this order.",
"name" : "The name of the rounding adjustment from the original sale Order.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"closed_at" : "Timestamp for when the order was closed. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\".",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charges" : [ {
"uid" : "Unique ID that identifies the service charge only within this order.",
"catalog_object_id" : "The catalog object ID referencing the service charge [CatalogObject](#type-catalogobject).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"calculation_phase" : "The calculation phase at which to apply the service charge. See [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"taxable" : "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.",
"percentage" : "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.",
"name" : "The name of the service charge.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ]
} ],
"version" : "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](/orders-api/manage-orders#update-orders).",
"tenders" : [ {
"transaction_id" : "The ID of the tender's associated transaction.",
"card_details" : {
"entry_method" : "The method used to enter the card's details for the transaction. See [TenderCardDetailsEntryMethod](#type-tendercarddetailsentrymethod) for possible values",
"card" : {
"last_4" : "The last 4 digits of the card number.",
"card_brand" : "The card's brand (such as `VISA`).\nSee [CardBrand](#type-cardbrand) for possible values",
"fingerprint" : "A unique, Square-assigned ID that identifies the card across multiple locations and applications for a single Square account.",
"exp_month" : "The expiration month of the associated card as an integer between 1 and 12.",
"billing_address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"id" : "Unique ID for this card. Generated by Square.",
"exp_year" : "The four-digit year of the card's expiration date.",
"cardholder_name" : "The name of the cardholder."
},
"status" : "The credit card payment's current state (such as `AUTHORIZED` or `CAPTURED`). See [TenderCardDetailsStatus](#type-tendercarddetailsstatus) for possible values"
},
"note" : "An optional note associated with the tender at the time of payment.",
"created_at" : "The time when the tender was created, in RFC 3339 format.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"type" : "The type of tender, such as `CARD` or `CASH`.\nSee [TenderType](#type-tendertype) for possible values",
"processing_fee_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"location_id" : "The ID of the transaction's associated location.",
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"payment_id" : "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.",
"cash_details" : {
"buyer_tendered_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"change_back_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"id" : "The tender's unique ID.",
"customer_id" : "If the tender is associated with a customer or represents a customer's card on file, this is the ID of the associated customer.",
"additional_recipients" : [ {
"receivable_id" : "The unique ID for this [AdditionalRecipientReceivable](#type-additionalrecipientreceivable), assigned by the server.",
"description" : "The description of the additional recipient.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"location_id" : "The location ID for a recipient (other than the merchant) receiving a portion of this tender."
} ]
} ],
"return_amounts" : {
"discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"returns" : [ {
"uid" : "Unique ID that identifies the return only within this order.",
"return_line_items" : [ {
"quantity_unit" : {
"precision" : "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.",
"measurement_unit" : {
"volume_unit" : "Represents a standard volume unit. See [MeasurementUnitVolume](#type-measurementunitvolume) for possible values",
"weight_unit" : "Represents a standard unit of weight or mass. See [MeasurementUnitWeight](#type-measurementunitweight) for possible values",
"generic_unit" : "Reserved for API integrations that lack the ability to specify a real measurement unit See [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values",
"area_unit" : "Represents a standard area unit. See [MeasurementUnitArea](#type-measurementunitarea) for possible values",
"type" : "Represents the type of the measurement unit. See [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values",
"custom_unit" : {
"name" : "The name of the custom unit, for example \"bushel\".",
"abbreviation" : "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears in the cart for the Point of Sale app, and in reports."
},
"length_unit" : "Represents a standard length unit. See [MeasurementUnitLength](#type-measurementunitlength) for possible values"
}
},
"note" : "The note of the returned line item.",
"catalog_object_id" : "The [CatalogItemVariation](#type-catalogitemvariation) id applied to this returned line item.",
"source_line_item_uid" : "`uid` of the LineItem in the original sale Order.",
"quantity" : "The quantity returned, formatted as a decimal number.\nFor example: `\"3\"`.\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example: `\"1.70000\"`.",
"gross_return_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"variation_name" : "The name of the variation applied to this returned line item.",
"uid" : "Unique identifier for this return line item entry.",
"variation_total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"return_modifiers" : [ {
"uid" : "Unique ID that identifies the return modifier only within this order.",
"source_modifier_uid" : "`uid` of the Modifier from the LineItem from the Order which contains the original sale of this line item modifier.",
"catalog_object_id" : "The catalog object id referencing [CatalogModifier](#type-catalogmodifier).",
"total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The name of the item modifier."
} ],
"name" : "The name of the line item.",
"total_discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ],
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_discounts" : [ {
"uid" : "Unique ID that identifies the applied discount only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"discount_uid" : "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`."
} ]
} ],
"rounding_adjustment" : {
"uid" : "Unique ID that identifies the rounding adjustment only within this order.",
"name" : "The name of the rounding adjustment from the original sale Order.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"return_amounts" : {
"discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"source_order_id" : "Order which contains the original sale of these returned line items. This will be unset for unlinked returns.",
"return_service_charges" : [ {
"uid" : "Unique ID that identifies the return service charge only within this order.",
"catalog_object_id" : "The catalog object ID of the associated [CatalogServiceCharge](#type-catalogservicecharge).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"calculation_phase" : "The calculation phase after which to apply the service charge. See [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"taxable" : "Indicates whether the surcharge can be taxed. Service charges\ncalculated in the `TOTAL_PHASE` cannot be marked as taxable.",
"percentage" : "The percentage of the service charge, as a string representation of\na decimal number. For example, a value of `\"7.25\"` corresponds to a\npercentage of 7.25%.\nExactly one of `percentage` or `amount_money` should be set.",
"name" : "The name of the service charge.",
"source_service_charge_uid" : "`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.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ]
} ],
"return_discounts" : [ {
"uid" : "Unique ID that identifies the return discount only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogDiscount](#type-catalogdiscount).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"source_discount_uid" : "`uid` of the Discount from the Order which contains the original application of this discount.",
"percentage" : "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.",
"scope" : "Indicates the level at which the `OrderReturnDiscount` applies. For `ORDER` scoped discounts, the server will generate references in `applied_discounts` on all `OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the discount will only apply to `OrderReturnLineItem`s with references in their `applied_discounts` field. See [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values",
"name" : "The discount's name.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"type" : "The type of the discount. If it is created by API, it would be either `FIXED_PERCENTAGE` or `FIXED_AMOUNT`. VARIABLE_* is not supported in API because the order is created at the time of sale and either percentage or amount has to be specified. See [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values"
} ],
"return_taxes" : [ {
"uid" : "Unique ID that identifies the return tax only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogTax](#type-catalogtax).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"percentage" : "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%.",
"scope" : "Indicates the level at which the `OrderReturnTax` applies. For `ORDER` scoped taxes, Square generates references in `applied_taxes` on all `OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax will only apply to `OrderReturnLineItem`s with references in their `applied_discounts` field. See [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values",
"source_tax_uid" : "`uid` of the Tax from the Order which contains the original charge of this tax.",
"name" : "The tax's name.",
"type" : "Indicates the calculation method used to apply the tax. See [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values"
} ]
} ],
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"customer_id" : "The [Customer](#type-customer) ID of the customer associated with the order."
}
}
}

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

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"birthday" : "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.",
"note" : "An optional note to associate with the customer.",
"email_address" : "The customer's email address.",
"address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"reference_id" : "An optional second ID you can set to associate the customer with an\nentity in another system.",
"company_name" : "The name of the customer's company.",
"nickname" : "A nickname for the customer.",
"idempotency_key" : "The idempotency key for the request.\tSee the [Idempotency](/basics/api101/idempotency)\nguide for more information.",
"phone_number" : "The customer's phone number.",
"given_name" : "The customer's given (i.e., first) name.",
"family_name" : "The customer's family (i.e., last) name."
}

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.

Parameters

customer_id (required)

The Square ID of the customer profile the card is linked to.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"card_nonce" : "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](/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" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"cardholder_name" : "The full name printed on the credit card.",
"verification_token" : "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."
}

create_discount

Creates a discount.

Parameters

location_id (required)

The ID of the location to create an item for.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"pin_required" : "Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment.",
"color" : "The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See [V1DiscountColor](#type-v1discountcolor) for possible values",
"rate" : "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.",
"name" : "The discount's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"amount_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"id" : "The discount's unique ID.",
"discount_type" : "Indicates whether the discount is a FIXED value or entered at the time of sale. See [V1DiscountDiscountType](#type-v1discountdiscounttype) for possible values"
}

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.

Employee entities cannot be deleted. To disable employee profiles,
set the employee's status to INACTIVE

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"updated_at" : "The time when the employee entity was most recently updated, in ISO 8601 format.",
"last_name" : "The employee's last name.",
"created_at" : "The time when the employee entity was created, in ISO 8601 format.",
"external_id" : "An ID the merchant can set to associate the employee with an entity in another system.",
"id" : "The employee's unique ID.",
"first_name" : "The employee's first name.",
"role_ids" : [ "string" ],
"email" : "The employee's email address.",
"authorized_location_ids" : [ "string" ],
"status" : "CWhether the employee is ACTIVE or INACTIVE. Inactive employees cannot sign in to Square Register.Merchants update this field from the Square Dashboard. See [V1EmployeeStatus](#type-v1employeestatus) for possible values"
}

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. 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.

Parameters

$body

An EmployeeRole object with a name and permissions, and an optional owner flag.

Type: object

{
"updated_at" : "The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated.",
"permissions" : [ "string" ],
"is_owner" : "If true, employees with this role have all permissions, regardless of the values indicated in permissions.",
"name" : "The role's merchant-defined name.",
"created_at" : "The time when the employee entity was created, in ISO 8601 format. Is set by Square when the Role is created.",
"id" : "The role's unique ID, Can only be set by Square."
}

create_fee

Creates a fee (tax).

Parameters

location_id (required)

The ID of the location to create a fee for.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"calculation_phase" : "Forthcoming See [V1FeeCalculationPhase](#type-v1feecalculationphase) for possible values",
"rate" : "The rate of the fee, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%.",
"name" : "The fee's name.",
"adjustment_type" : "The type of adjustment the fee applies to a payment. Currently, this value is TAX for all fees. See [V1FeeAdjustmentType](#type-v1feeadjustmenttype) for possible values",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The fee's unique ID.",
"inclusion_type" : "Whether the fee is ADDITIVE or INCLUSIVE. See [V1FeeInclusionType](#type-v1feeinclusiontype) for possible values",
"type" : "In countries with multiple classifications for sales taxes, indicates which classification the fee falls under. Currently relevant only to Canadian merchants. See [V1FeeType](#type-v1feetype) for possible values",
"applies_to_custom_amounts" : "If true, the fee applies to custom amounts entered into Square Register that are not associated with a particular item.",
"enabled" : "If true, the fee is applied to all appropriate items. If false, the fee is not applied at all."
}

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.

Parameters

location_id (required)

The ID of the location to create an item for.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"master_image" : {
"id" : "The image's unique ID.",
"url" : "The image's publicly accessible URL."
},
"fees" : [ {
"calculation_phase" : "Forthcoming See [V1FeeCalculationPhase](#type-v1feecalculationphase) for possible values",
"rate" : "The rate of the fee, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%.",
"name" : "The fee's name.",
"adjustment_type" : "The type of adjustment the fee applies to a payment. Currently, this value is TAX for all fees. See [V1FeeAdjustmentType](#type-v1feeadjustmenttype) for possible values",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The fee's unique ID.",
"inclusion_type" : "Whether the fee is ADDITIVE or INCLUSIVE. See [V1FeeInclusionType](#type-v1feeinclusiontype) for possible values",
"type" : "In countries with multiple classifications for sales taxes, indicates which classification the fee falls under. Currently relevant only to Canadian merchants. See [V1FeeType](#type-v1feetype) for possible values",
"applies_to_custom_amounts" : "If true, the fee applies to custom amounts entered into Square Register that are not associated with a particular item.",
"enabled" : "If true, the fee is applied to all appropriate items. If false, the fee is not applied at all."
} ],
"color" : "The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See [V1ItemColor](#type-v1itemcolor) for possible values",
"visibility" : "Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See [V1ItemVisibility](#type-v1itemvisibility) for possible values",
"taxable" : "Deprecated. This field is not used.",
"description" : "The item's description.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"type" : "The item's type. This value is NORMAL for almost all items.\nSee [V1ItemType](#type-v1itemtype) for possible values",
"abbreviation" : "The text of the item's display label in Square Register. Only up to the first five characters of the string are used.",
"modifier_lists" : [ {
"selection_type" : "Indicates whether MULTIPLE options or a SINGLE option from the modifier list can be applied to a single item. See [V1ModifierListSelectionType](#type-v1modifierlistselectiontype) for possible values",
"name" : "The modifier list's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The modifier list's unique ID.",
"modifier_options" : [ {
"price_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"on_by_default" : "If true, the modifier option is the default option in a modifier list for which selection_type is SINGLE.",
"name" : "The modifier option's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The modifier option's unique ID.",
"modifier_list_id" : "The ID of the modifier list the option belongs to.",
"ordinal" : "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."
} ]
} ],
"category_id" : "The ID of the item's category, if any.",
"variations" : [ {
"pricing_type" : "Indicates whether the item variation's price is fixed or determined at the time of sale. See [V1VariationPricingType](#type-v1variationpricingtype) for possible values",
"price_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"item_id" : "The ID of the variation's associated item.",
"inventory_alert_threshold" : "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.",
"name" : "The item variation's name.",
"track_inventory" : "If true, inventory tracking is active for the variation.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The item variation's unique ID.",
"user_data" : "Arbitrary metadata associated with the variation. Cannot exceed 255 characters.",
"sku" : "The item variation's SKU, if any.",
"ordinal" : "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",
"inventory_alert_type" : "Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its inventory_alert_threshold. See [V1VariationInventoryAlertType](#type-v1variationinventoryalerttype) for possible values"
} ],
"name" : "The item's name.",
"id" : "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 (_).",
"category" : {
"name" : "The category's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The category's unique ID."
},
"available_online" : "If true, the item can be added to shipping orders from the merchant's online store.",
"available_for_pickup" : "If true, the item can be added to pickup orders from the merchant's online store. Default value: false"
}

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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"location_id" : "The Square location ID the authorization code should be tied to."
}

create_modifier_list

Creates an item modifier list and at least one modifier option for it.

Parameters

location_id (required)

The ID of the location to create a modifier list for.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"selection_type" : "Indicates whether MULTIPLE options or a SINGLE option from the modifier list can be applied to a single item. See [V1ModifierListSelectionType](#type-v1modifierlistselectiontype) for possible values",
"name" : "The modifier list's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The modifier list's unique ID.",
"modifier_options" : [ {
"price_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"on_by_default" : "If true, the modifier option is the default option in a modifier list for which selection_type is SINGLE.",
"name" : "The modifier option's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The modifier option's unique ID.",
"modifier_list_id" : "The ID of the modifier list the option belongs to.",
"ordinal" : "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."
} ]
}

create_modifier_option

Creates an item modifier option and adds it to a modifier list.

Parameters

location_id (required)

The ID of the item's associated location.

Type: string

modifier_list_id (required)

The ID of the modifier list to edit.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"price_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"on_by_default" : "If true, the modifier option is the default option in a modifier list for which selection_type is SINGLE.",
"name" : "The modifier option's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The modifier option's unique ID.",
"modifier_list_id" : "The ID of the modifier list the option belongs to.",
"ordinal" : "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."
}

create_order

Creates a new 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 guide. You can modify open orders using the UpdateOrder endpoint. To learn more about the Orders API, see the Orders API Overview.

Parameters

location_id (required)

The ID of the business location to associate the order with.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"idempotency_key" : "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](/basics/api101/idempotency) for more information.",
"order" : {
"reference_id" : "A client specified identifier to associate an entity in another system with this order.",
"taxes" : [ {
"uid" : "Unique ID that identifies the tax only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogTax](#type-catalogtax).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"percentage" : "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%.",
"scope" : "Indicates the level at which the tax applies. For `ORDER` scoped taxes, Square generates references in `applied_taxes` on all order line items that do not have them. For `LINE_ITEM` scoped taxes, the tax will only apply to line items with references in their `applied_taxes` field. This field is immutable. To change the scope, you must delete the tax and re-add it as a new tax. See [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values",
"name" : "The tax's name.",
"type" : "Indicates the calculation method used to apply the tax. See [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values"
} ],
"created_at" : "Timestamp for when the order was created. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\".",
"source" : {
"name" : "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."
},
"line_items" : [ {
"quantity_unit" : {
"precision" : "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.",
"measurement_unit" : {
"volume_unit" : "Represents a standard volume unit. See [MeasurementUnitVolume](#type-measurementunitvolume) for possible values",
"weight_unit" : "Represents a standard unit of weight or mass. See [MeasurementUnitWeight](#type-measurementunitweight) for possible values",
"generic_unit" : "Reserved for API integrations that lack the ability to specify a real measurement unit See [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values",
"area_unit" : "Represents a standard area unit. See [MeasurementUnitArea](#type-measurementunitarea) for possible values",
"type" : "Represents the type of the measurement unit. See [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values",
"custom_unit" : {
"name" : "The name of the custom unit, for example \"bushel\".",
"abbreviation" : "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears in the cart for the Point of Sale app, and in reports."
},
"length_unit" : "Represents a standard length unit. See [MeasurementUnitLength](#type-measurementunitlength) for possible values"
}
},
"note" : "The note of the line item.",
"catalog_object_id" : "The [CatalogItemVariation](#type-catalogitemvariation) id applied to this line item.",
"quantity" : "The quantity purchased, formatted as a decimal number.\nFor example: `\"3\"`.\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example: `\"1.70000\"`.",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"variation_name" : "The name of the variation applied to this line item.",
"modifiers" : [ {
"uid" : "Unique ID that identifies the modifier only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogModifier](#type-catalogmodifier).",
"total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The name of the item modifier."
} ],
"gross_sales_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"uid" : "Unique ID that identifies the line item only within this order.",
"variation_total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The name of the line item.",
"total_discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ],
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_discounts" : [ {
"uid" : "Unique ID that identifies the applied discount only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"discount_uid" : "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`."
} ]
} ],
"location_id" : "The ID of the merchant location this order is associated with.",
"refunds" : [ {
"transaction_id" : "The ID of the transaction that the refunded tender is part of.",
"reason" : "The reason for the refund being issued.",
"tender_id" : "The ID of the refunded tender.",
"created_at" : "The time when the refund was created, in RFC 3339 format.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"id" : "The refund's unique ID.",
"processing_fee_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"additional_recipients" : [ {
"receivable_id" : "The unique ID for this [AdditionalRecipientReceivable](#type-additionalrecipientreceivable), assigned by the server.",
"description" : "The description of the additional recipient.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"location_id" : "The location ID for a recipient (other than the merchant) receiving a portion of this tender."
} ],
"location_id" : "The ID of the refund's associated location.",
"status" : "The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`,\nor `FAILED`).\nSee [RefundStatus](#type-refundstatus) for possible values"
} ],
"fulfillments" : [ {
"uid" : "Unique ID that identifies the fulfillment only within this order.",
"pickup_details" : {
"note" : "A note meant to provide additional instructions about the pickup fulfillment displayed in the Square Point of Sale and set by the API.",
"schedule_type" : "The schedule type of the pickup fulfillment. Defaults to `SCHEDULED`. See [OrderFulfillmentPickupDetailsScheduleType](#type-orderfulfillmentpickupdetailsscheduletype) for possible values",
"rejected_at" : "The [timestamp](#workingwithdates) indicating when the fulfillment was rejected. In RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"pickup_at" : "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.",
"canceled_at" : "The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\", indicating when the fulfillment was canceled.",
"pickup_window_duration" : "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.",
"expired_at" : "The [timestamp](#workingwithdates) indicating when the fulfillment expired. In RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"placed_at" : "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" : "The [timestamp](#workingwithdates) indicating when the fulfillment\nwas accepted. In RFC3339 timestamp format,\ne.g., \"2016-09-04T23:59:33.123Z\".",
"cancel_reason" : "A description of why the pickup was canceled. Max length: 100 characters.",
"expires_at" : "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.",
"ready_at" : "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\".",
"picked_up_at" : "The [timestamp](#workingwithdates) indicating when the fulfillment\nwas picked up by the recipient. In RFC3339 timestamp format,\ne.g., \"2016-09-04T23:59:33.123Z\".",
"recipient" : {
"email_address" : "The email address of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"phone_number" : "The phone number of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"customer_id" : "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" : "The display name of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`."
},
"auto_complete_duration" : "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.",
"prep_time_duration" : "The duration of time it takes to prepare this fulfillment.\nMust be in RFC3339 duration format, e.g., \"P1W3D\"."
},
"shipment_details" : {
"packaged_at" : "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\".",
"shipped_at" : "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\".",
"shipping_note" : "A note with additional information for the shipping carrier.",
"expected_shipped_at" : "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\".",
"canceled_at" : "The [timestamp](#workingwithdates) indicating the shipment was canceled. Must be in RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"shipping_type" : "A description of the type of shipping product purchased from the carrier. e.g. First Class, Priority, Express",
"in_progress_at" : "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\".",
"failure_reason" : "A description of why the shipment failed to be completed.",
"placed_at" : "The [timestamp](#workingwithdates) indicating when the shipment was requested. Must be in RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"carrier" : "The shipping carrier being used to ship this fulfillment\ne.g. UPS, FedEx, USPS, etc.",
"cancel_reason" : "A description of why the shipment was canceled.",
"recipient" : {
"email_address" : "The email address of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"phone_number" : "The phone number of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"customer_id" : "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" : "The display name of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`."
},
"tracking_number" : "The reference number provided by the carrier to track the shipment's progress.",
"failed_at" : "The [timestamp](#workingwithdates) indicating when the shipment\nfailed to be completed. Must be in RFC3339 timestamp format, e.g.,\n\"2016-09-04T23:59:33.123Z\".",
"tracking_url" : "A link to the tracking webpage on the carrier's website."
},
"state" : "The state of the fulfillment. See [OrderFulfillmentState](#type-orderfulfillmentstate) for possible values",
"type" : "The type of the fulfillment. See [OrderFulfillmentType](#type-orderfulfillmenttype) for possible values"
} ],
"discounts" : [ {
"uid" : "Unique ID that identifies the discount only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogDiscount](#type-catalogdiscount).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"percentage" : "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.",
"scope" : "Indicates the level at which the discount applies. For `ORDER` scoped discounts, Square generates references in `applied_discounts` on all order line items that do not have them. For `LINE_ITEM` scoped discounts, the discount only applies to line items with a discount reference in their `applied_discounts` field. This field is immutable. To change the scope of a discount you must delete the discount and re-add it as a new discount. See [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values",
"name" : "The discount's name.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"type" : "The type of the discount. If it is created by API, it would be either `FIXED_PERCENTAGE` or `FIXED_AMOUNT`. VARIABLE_* is not supported in API because the order is created at the time of sale and either percentage or amount has to be specified. See [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values"
} ],
"updated_at" : "Timestamp for when the order was last updated. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\".",
"total_discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"net_amounts" : {
"discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"id" : "The order's unique ID.",
"state" : "The current state of the order. `OPEN`,`COMPLETED`,`CANCELED`\nSee [OrderState](#type-orderstate) for possible values",
"rounding_adjustment" : {
"uid" : "Unique ID that identifies the rounding adjustment only within this order.",
"name" : "The name of the rounding adjustment from the original sale Order.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"closed_at" : "Timestamp for when the order was closed. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\".",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charges" : [ {
"uid" : "Unique ID that identifies the service charge only within this order.",
"catalog_object_id" : "The catalog object ID referencing the service charge [CatalogObject](#type-catalogobject).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"calculation_phase" : "The calculation phase at which to apply the service charge. See [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"taxable" : "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.",
"percentage" : "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.",
"name" : "The name of the service charge.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ]
} ],
"version" : "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](/orders-api/manage-orders#update-orders).",
"tenders" : [ {
"transaction_id" : "The ID of the tender's associated transaction.",
"card_details" : {
"entry_method" : "The method used to enter the card's details for the transaction. See [TenderCardDetailsEntryMethod](#type-tendercarddetailsentrymethod) for possible values",
"card" : {
"last_4" : "The last 4 digits of the card number.",
"card_brand" : "The card's brand (such as `VISA`).\nSee [CardBrand](#type-cardbrand) for possible values",
"fingerprint" : "A unique, Square-assigned ID that identifies the card across multiple locations and applications for a single Square account.",
"exp_month" : "The expiration month of the associated card as an integer between 1 and 12.",
"billing_address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"id" : "Unique ID for this card. Generated by Square.",
"exp_year" : "The four-digit year of the card's expiration date.",
"cardholder_name" : "The name of the cardholder."
},
"status" : "The credit card payment's current state (such as `AUTHORIZED` or `CAPTURED`). See [TenderCardDetailsStatus](#type-tendercarddetailsstatus) for possible values"
},
"note" : "An optional note associated with the tender at the time of payment.",
"created_at" : "The time when the tender was created, in RFC 3339 format.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"type" : "The type of tender, such as `CARD` or `CASH`.\nSee [TenderType](#type-tendertype) for possible values",
"processing_fee_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"location_id" : "The ID of the transaction's associated location.",
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"payment_id" : "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.",
"cash_details" : {
"buyer_tendered_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"change_back_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"id" : "The tender's unique ID.",
"customer_id" : "If the tender is associated with a customer or represents a customer's card on file, this is the ID of the associated customer.",
"additional_recipients" : [ {
"receivable_id" : "The unique ID for this [AdditionalRecipientReceivable](#type-additionalrecipientreceivable), assigned by the server.",
"description" : "The description of the additional recipient.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"location_id" : "The location ID for a recipient (other than the merchant) receiving a portion of this tender."
} ]
} ],
"return_amounts" : {
"discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"returns" : [ {
"uid" : "Unique ID that identifies the return only within this order.",
"return_line_items" : [ {
"quantity_unit" : {
"precision" : "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.",
"measurement_unit" : {
"volume_unit" : "Represents a standard volume unit. See [MeasurementUnitVolume](#type-measurementunitvolume) for possible values",
"weight_unit" : "Represents a standard unit of weight or mass. See [MeasurementUnitWeight](#type-measurementunitweight) for possible values",
"generic_unit" : "Reserved for API integrations that lack the ability to specify a real measurement unit See [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values",
"area_unit" : "Represents a standard area unit. See [MeasurementUnitArea](#type-measurementunitarea) for possible values",
"type" : "Represents the type of the measurement unit. See [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values",
"custom_unit" : {
"name" : "The name of the custom unit, for example \"bushel\".",
"abbreviation" : "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears in the cart for the Point of Sale app, and in reports."
},
"length_unit" : "Represents a standard length unit. See [MeasurementUnitLength](#type-measurementunitlength) for possible values"
}
},
"note" : "The note of the returned line item.",
"catalog_object_id" : "The [CatalogItemVariation](#type-catalogitemvariation) id applied to this returned line item.",
"source_line_item_uid" : "`uid` of the LineItem in the original sale Order.",
"quantity" : "The quantity returned, formatted as a decimal number.\nFor example: `\"3\"`.\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example: `\"1.70000\"`.",
"gross_return_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"variation_name" : "The name of the variation applied to this returned line item.",
"uid" : "Unique identifier for this return line item entry.",
"variation_total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"return_modifiers" : [ {
"uid" : "Unique ID that identifies the return modifier only within this order.",
"source_modifier_uid" : "`uid` of the Modifier from the LineItem from the Order which contains the original sale of this line item modifier.",
"catalog_object_id" : "The catalog object id referencing [CatalogModifier](#type-catalogmodifier).",
"total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The name of the item modifier."
} ],
"name" : "The name of the line item.",
"total_discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ],
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_discounts" : [ {
"uid" : "Unique ID that identifies the applied discount only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"discount_uid" : "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`."
} ]
} ],
"rounding_adjustment" : {
"uid" : "Unique ID that identifies the rounding adjustment only within this order.",
"name" : "The name of the rounding adjustment from the original sale Order.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"return_amounts" : {
"discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"source_order_id" : "Order which contains the original sale of these returned line items. This will be unset for unlinked returns.",
"return_service_charges" : [ {
"uid" : "Unique ID that identifies the return service charge only within this order.",
"catalog_object_id" : "The catalog object ID of the associated [CatalogServiceCharge](#type-catalogservicecharge).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"calculation_phase" : "The calculation phase after which to apply the service charge. See [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"taxable" : "Indicates whether the surcharge can be taxed. Service charges\ncalculated in the `TOTAL_PHASE` cannot be marked as taxable.",
"percentage" : "The percentage of the service charge, as a string representation of\na decimal number. For example, a value of `\"7.25\"` corresponds to a\npercentage of 7.25%.\nExactly one of `percentage` or `amount_money` should be set.",
"name" : "The name of the service charge.",
"source_service_charge_uid" : "`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.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ]
} ],
"return_discounts" : [ {
"uid" : "Unique ID that identifies the return discount only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogDiscount](#type-catalogdiscount).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"source_discount_uid" : "`uid` of the Discount from the Order which contains the original application of this discount.",
"percentage" : "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.",
"scope" : "Indicates the level at which the `OrderReturnDiscount` applies. For `ORDER` scoped discounts, the server will generate references in `applied_discounts` on all `OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the discount will only apply to `OrderReturnLineItem`s with references in their `applied_discounts` field. See [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values",
"name" : "The discount's name.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"type" : "The type of the discount. If it is created by API, it would be either `FIXED_PERCENTAGE` or `FIXED_AMOUNT`. VARIABLE_* is not supported in API because the order is created at the time of sale and either percentage or amount has to be specified. See [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values"
} ],
"return_taxes" : [ {
"uid" : "Unique ID that identifies the return tax only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogTax](#type-catalogtax).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"percentage" : "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%.",
"scope" : "Indicates the level at which the `OrderReturnTax` applies. For `ORDER` scoped taxes, Square generates references in `applied_taxes` on all `OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax will only apply to `OrderReturnLineItem`s with references in their `applied_discounts` field. See [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values",
"source_tax_uid" : "`uid` of the Tax from the Order which contains the original charge of this tax.",
"name" : "The tax's name.",
"type" : "Indicates the calculation method used to apply the tax. See [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values"
} ]
} ],
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"customer_id" : "The [Customer](#type-customer) ID of the customer associated with the order."
}
}

create_page

Creates a Favorites page in Square Register.

Parameters

location_id (required)

The ID of the location to create an item for.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"cells" : [ {
"page_id" : "The unique identifier of the page the cell is included on.",
"object_type" : "The type of entity represented in the cell (ITEM, DISCOUNT, CATEGORY, or PLACEHOLDER). See [V1PageCellObjectType](#type-v1pagecellobjecttype) for possible values",
"placeholder_type" : "For a cell with an object_type of PLACEHOLDER, this value indicates the cell's special behavior. See [V1PageCellPlaceholderType](#type-v1pagecellplaceholdertype) for possible values",
"column" : "The column of the cell. Always an integer between 0 and 4, inclusive.",
"row" : "The row of the cell. Always an integer between 0 and 4, inclusive.",
"object_id" : "The unique identifier of the entity represented in the cell. Not present for cells with an object_type of PLACEHOLDER."
} ],
"page_index" : "The page's position in the merchant's list of pages. Always an integer between 0 and 6, inclusive.",
"name" : "The page's name, if any.",
"id" : "The page's unique identifier."
}

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. The PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission is required to enable application fees.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"note" : "An optional note to be entered by the developer when creating a payment Limit 500 characters.",
"app_fee_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"reference_id" : "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.",
"accept_partial_authorization" : "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](/payments-api/take-payments#partial-payment-gift-card). Default: false",
"buyer_email_address" : "The buyer's e-mail address",
"autocomplete" : "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](/payments-api/take-payments#delayed-payments). Default: true",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"billing_address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"location_id" : "The location ID to associate with the payment. If not specified, the default location is used.",
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"idempotency_key" : "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](/basics/api101/idempotency) for more information.",
"source_id" : "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.",
"shipping_address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"customer_id" : "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.",
"order_id" : "Associate a previously created order with this payment",
"verification_token" : "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](/sca-overview) for more."
}

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 Breaks 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

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"shift" : {
"end_at" : "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).",
"breaks" : [ {
"end_at" : "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" : "The `BreakType` this `Break` was templated on.",
"name" : "A human-readable name.",
"expected_duration" : "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthe break.",
"id" : "UUID for this object",
"is_paid" : "Whether this break counts towards time worked for compensation\npurposes.",
"start_at" : "RFC 3339; follows same timezone info as `Shift`. Precision up to\nthe minute is respected; seconds are truncated."
} ],
"updated_at" : "A read-only timestamp in RFC 3339 format; presented in UTC.",
"timezone" : "Read-only convenience value that is calculated from the location based on `location_id`. Format: the IANA Timezone Database identifier for the location timezone.",
"employee_id" : "The ID of the employee this shift belongs to.",
"created_at" : "A read-only timestamp in RFC 3339 format; presented in UTC.",
"id" : "UUID for this object",
"start_at" : "RFC 3339; shifted to location timezone + offset. Precision up to the\nminute is respected; seconds are truncated.",
"version" : "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.",
"location_id" : "The ID of the location this shift occurred at. Should be based on\nwhere the employee clocked in.",
"wage" : {
"hourly_rate" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"title" : "The name of the job performed during this shift. Square\nlabor-reporting UIs may group shifts together by title."
},
"status" : "Describes working state of the current `Shift`.\nSee [ShiftStatus](#type-shiftstatus) for possible values"
},
"idempotency_key" : "Unique string value to insure the idempotency of the operation."
}

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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"deleted" : "If true, the timecard was deleted by the merchant, and it is no longer valid.",
"doubletime_seconds_worked" : "The total number of doubletime seconds worked in the timecard.",
"updated_at" : "The time when the timecard was most recently updated, in ISO 8601 format.",
"clockin_time" : "The clock-in time for the timecard, in ISO 8601 format.",
"employee_id" : "The ID of the employee the timecard is associated with.",
"overtime_seconds_worked" : "The total number of overtime seconds worked in the timecard.",
"clockin_location_id" : "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.",
"created_at" : "The time when the timecard was created, in ISO 8601 format.",
"clockout_time" : "The clock-out time for the timecard, in ISO 8601 format. Provide this value only if importing timecard information from another system.",
"id" : "The timecard's unique ID.",
"regular_seconds_worked" : "The total number of regular (non-overtime) seconds worked in the timecard.",
"clockout_location_id" : "The ID of the location the employee clocked out from. Provide this value only if importing timecard information from another system."
}

create_variation

Creates an item variation for an existing item.

Parameters

item_id (required)

The item's ID.

Type: string

location_id (required)

The ID of the item's associated location.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"pricing_type" : "Indicates whether the item variation's price is fixed or determined at the time of sale. See [V1VariationPricingType](#type-v1variationpricingtype) for possible values",
"price_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"item_id" : "The ID of the variation's associated item.",
"inventory_alert_threshold" : "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.",
"name" : "The item variation's name.",
"track_inventory" : "If true, inventory tracking is active for the variation.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The item variation's unique ID.",
"user_data" : "Arbitrary metadata associated with the variation. Cannot exceed 255 characters.",
"sku" : "The item variation's SKU, if any.",
"ordinal" : "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",
"inventory_alert_type" : "Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its inventory_alert_threshold. See [V1VariationInventoryAlertType](#type-v1variationinventoryalerttype) for possible values"
}

delete_break_type

Deletes an existing BreakType.
A BreakType can be deleted even if it is referenced from a Shift.

Parameters

id (required)

UUID for the BreakType being deleted.

Type: string

delete_catalog_object

Deletes a single 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 will also delete all of its CatalogItemVariation children.

Parameters

object_id (required)

The ID of the 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 will delete its CatalogItemVariations).

Type: string

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.

Parameters

category_id (required)

The ID of the category to delete.

Type: string

location_id (required)

The ID of the item's associated location.

Type: string

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.

Parameters

customer_id (required)

The ID of the customer to delete.

Type: string

delete_customer_card

Removes a card on file from a customer.

Parameters

card_id (required)

The ID of the card on file to delete.

Type: string

customer_id (required)

The ID of the customer that the card on file belongs to.

Type: string

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.

Parameters

discount_id (required)

The ID of the discount to delete.

Type: string

location_id (required)

The ID of the item's associated location.

Type: string

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.

Parameters

fee_id (required)

The ID of the fee to delete.

Type: string

location_id (required)

The ID of the fee's associated location.

Type: string

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.

Parameters

item_id (required)

The ID of the item to modify.

Type: string

location_id (required)

The ID of the item's associated location.

Type: string

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.

Parameters

location_id (required)

The ID of the item's associated location.

Type: string

modifier_list_id (required)

The ID of the modifier list to delete.

Type: string

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.

Parameters

location_id (required)

The ID of the item's associated location.

Type: string

modifier_list_id (required)

The ID of the modifier list to delete.

Type: string

modifier_option_id (required)

The ID of the modifier list to edit.

Type: string

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.

Parameters

location_id (required)

The ID of the Favorites page's associated location.

Type: string

page_id (required)

The ID of the page to delete.

Type: string

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.

Parameters

location_id (required)

The ID of the Favorites page's associated location.

Type: string

page_id (required)

The ID of the page to delete.

Type: string

column

The column of the cell to clear. Always an integer between 0 and 4, inclusive. Column 0 is the leftmost column.

Type: string

row

The row of the cell to clear. Always an integer between 0 and 4, inclusive. Row 0 is the top row.

Type: string

delete_shift

Deletes a Shift.

Parameters

id (required)

UUID for the Shift being deleted.

Type: string

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. To filter deleted timecards, include the deleted query parameter in the list request. Only approved accounts can manage their employees with Square. Unapproved accounts cannot use employee management features with the API.

Parameters

timecard_id (required)

The ID of the timecard to delete.

Type: string

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.

Parameters

item_id (required)

The ID of the item to delete.

Type: string

location_id (required)

The ID of the item's associated location.

Type: string

variation_id (required)

The ID of the variation to delete.

Type: string

get_break_type

Returns a single BreakType specified by id.

Parameters

id (required)

UUID for the BreakType being retrieved.

Type: string

get_employee_wage

Returns a single EmployeeWage specified by id.

Parameters

id (required)

UUID for the EmployeeWage being retrieved.

Type: string

get_payment

Retrieves details for a specific Payment.

Parameters

payment_id (required)

Unique ID for the desired Payment.

Type: string

get_payment_refund

Retrieves a specific Refund using the refund_id.

Parameters

refund_id (required)

Unique ID for the desired PaymentRefund.

Type: string

get_shift

Returns a single Shift specified by id.

Parameters

id (required)

UUID for the Shift being retrieved.

Type: string

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.

Parameters

location_id (required)

The ID of the location to list bank accounts for.

Type: string

list_break_types

Returns a paginated list of BreakType instances for a business.

Parameters

location_id

Filter Break Types returned to only those that are associated with the specified location.

Type: string

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.

Parameters

location_id (required)

The ID of the location to list cash drawer shifts for.

Type: string

begin_time

The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time minus 90 days.

Type: string

end_time

The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time.

Type: string

order

The order in which cash drawer shifts are listed in the response, based on their created_at field. Default value: ASC

Type: string

list_catalog

Returns a list of CatalogObjects that includes all objects of a set of desired types (for example, all CatalogItem and CatalogTax objects) in the catalog. The types parameter is specified as a comma-separated list of valid 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.

Parameters

types

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 enumeration, namely ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, or IMAGE.

Type: string

list_categories

Lists all of a location's item categories.

Parameters

location_id (required)

The ID of the location to list categories for.

Type: string

list_customers

Lists a business's customers.

Parameters

sort_field

Indicates how Customers should be sorted. Default: DEFAULT.

Type: string

sort_order

Indicates whether Customers should be sorted in ascending (ASC) or
descending (DESC) order. Default: ASC.

Type: string

list_discounts

Lists all of a location's discounts.

Parameters

location_id (required)

The ID of the location to list categories for.

Type: string

list_employee_roles

Provides summary information for all of a business's employee roles.

Parameters

batch_token

A pagination cursor to retrieve the next set of results for your
original query to the endpoint.

Type: string

limit

The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.

Type: integer

order

The order in which employees are listed in the response, based on their created_at field.Default value: ASC

Type: string

list_employee_wages

Returns a paginated list of EmployeeWage instances for a business.

Parameters

employee_id

Filter wages returned to only those that are associated with the
specified employee.

Type: string

list_employees

Gets a list of Employee objects for a business.

Parameters

location_id

Filter employees returned to only those that are associated with the
specified location.

Type: string

status

Specifies the EmployeeStatus to filter the employee by.

Type: string

list_fees

Lists all of a location's fees (taxes).

Parameters

location_id (required)

The ID of the location to list fees for.

Type: string

list_inventory

Provides inventory information for all of a merchant's inventory-enabled item variations.

Parameters

location_id (required)

The ID of the item's associated location.

Type: string

batch_token

A pagination cursor to retrieve the next set of results for your
original query to the endpoint.

Type: string

limit

The maximum number of inventory entries to return in a single response. This value cannot exceed 1000.

Type: integer

list_items

Provides summary information for all of a location's items.

Parameters

location_id (required)

The ID of the location to list items for.

Type: string

batch_token

A pagination cursor to retrieve the next set of results for your
original query to the endpoint.

Type: string

list_locations

This operation has no parameters

list_modifier_lists

Lists all of a location's modifier lists.

Parameters

location_id (required)

The ID of the location to list modifier lists for.

Type: string

list_orders

Provides summary information for a merchant's online store orders.

Parameters

location_id (required)

The ID of the location to list online store orders for.

Type: string

batch_token

A pagination cursor to retrieve the next set of results for your
original query to the endpoint.

Type: string

limit

The maximum number of payments to return in a single response. This value cannot exceed 200.

Type: integer

order

TThe order in which payments are listed in the response.

Type: string

list_pages

Lists all of a location's Favorites pages in Square Register.

Parameters

location_id (required)

The ID of the location to list Favorites pages for.

Type: string

list_payment_refunds

Retrieves a list of refunds for the account making the request.
Max results per page: 100

Parameters

begin_time

Timestamp for the beginning of the requested reporting period, in RFC 3339 format. Default: The current time minus one year.

Type: string

end_time

Timestamp for the end of the requested reporting period, in RFC 3339 format. Default: The current time.

Type: string

location_id

ID of location associated with payment.

Type: string

sort_order

The order in which results are listed.

  • ASC - oldest to newest
  • DESC - newest to oldest (default).

Type: string

source_type

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.

Type: string

status

If provided, only refunds with the given status are returned. For a list of refund status values, see PaymentRefund. Default: If omitted refunds are returned regardless of status.

Type: string

list_payments

Retrieves a list of payments taken by the account making the request.
Max results per page: 100

Parameters

begin_time

Timestamp for the beginning of the reporting period, in RFC 3339 format. Inclusive. Default: The current time minus one year.

Type: string

card_brand

The brand of Payment card. For example, VISA

Type: string

end_time

Timestamp for the end of the requested reporting period, in RFC 3339 format. Default: The current time.

Type: string

last_4

The last 4 digits of Payment card.

Type: string

location_id

ID of location associated with payment

Type: string

sort_order

The order in which results are listed.

  • ASC - oldest to newest
  • DESC - newest to oldest (default).

Type: string

total

The exact amount in the total_money for a Payment.

Type: integer

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.

Parameters

location_id (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.

Type: string

batch_token

A pagination cursor to retrieve the next set of results for your
original query to the endpoint.

Type: string

begin_time

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.

Type: string

end_time

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.

Type: string

limit

The maximum number of payments to return in a single response. This value cannot exceed 200.

Type: integer

order

TThe order in which payments are listed in the response.

Type: string

status

Provide this parameter to retrieve only settlements with a particular status (SENT or FAILED).

Type: string

list_timecard_events

Provides summary information for all events associated with a
particular timecard.

Only approved accounts can manage their employees with Square.
Unapproved accounts cannot use employee management features with the
API.

Parameters

timecard_id (required)

The ID of the timecard to list events for.

Type: string

list_timecards

Provides summary information for all of a business's employee timecards.

Parameters

batch_token

A pagination cursor to retrieve the next set of results for your
original query to the endpoint.

Type: string

begin_clockin_time

If filtering results by their clockin_time field, the beginning of the requested reporting period, in ISO 8601 format.

Type: string

begin_clockout_time

If filtering results by their clockout_time field, the beginning of the requested reporting period, in ISO 8601 format.

Type: string

begin_updated_at

If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format.

Type: string

deleted

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.

Type: boolean

employee_id

If provided, the endpoint returns only timecards for the employee with the specified ID.

Type: string

end_clockin_time

If filtering results by their clockin_time field, the end of the requested reporting period, in ISO 8601 format.

Type: string

end_clockout_time

If filtering results by their clockout_time field, the end of the requested reporting period, in ISO 8601 format.

Type: string

end_updated_at

If filtering results by their updated_at field, the end of the requested reporting period, in ISO 8601 format.

Type: string

limit

The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.

Type: integer

order

The order in which timecards are listed in the response, based on their created_at field.

Type: string

list_workweek_configs

Returns a list of WorkweekConfig instances for a business.

This operation has no parameters

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. 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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"refresh_token" : "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" : "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](/authz/oauth/migration).",
"code" : "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.",
"grant_type" : "Specifies the method to request an OAuth access token. Valid values are: `authorization_code`, `refresh_token`, and `migration_token`",
"client_secret" : "The Square-issued application secret for your application, available from the [application dashboard](https://connect.squareup.com/apps).",
"redirect_uri" : "The redirect URL assigned in the [application dashboard](https://connect.squareup.com/apps).",
"client_id" : "The Square-issued ID of your application, available from the [application dashboard](https://connect.squareup.com/apps)."
}

pay_order

Pay for an order using one or more approved payments, 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. Any approved payments that reference the same order_id not specified in the payment_ids will be canceled. - Be approved with 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.

Parameters

order_id (required)

The ID of the order being paid.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"idempotency_key" : "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](/working-with-apis/idempotency) for more information.",
"payment_ids" : [ "string" ],
"order_version" : "The version of the order being paid. If not supplied, the latest version will be paid."
}

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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"reason" : "A description of the reason for the refund.",
"app_fee_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"payment_id" : "Unique ID of the payment being refunded.",
"idempotency_key" : "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](/basics/api101/idempotency).",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
}

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 guide.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"domain_name" : "A domain name as described in RFC-1034 that will be registered with ApplePay"
}

remove_fee

Removes a fee assocation from an item, meaning the fee is no longer automatically applied to the item in Square Register.

Parameters

fee_id (required)

The ID of the fee to apply.

Type: string

item_id (required)

The ID of the item to add the fee to.

Type: string

location_id (required)

The ID of the fee's associated location.

Type: string

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.

Parameters

item_id (required)

The ID of the item to remove the modifier list from.

Type: string

location_id (required)

The ID of the item's associated location.

Type: string

modifier_list_id (required)

The ID of the modifier list to remove.

Type: string

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.

Parameters

bank_account_id (required)

The bank account's Square-issued ID. You obtain this value from Settlement objects returned.

Type: string

location_id (required)

The ID of the bank account's associated location.

Type: string

retrieve_business

This operation has no parameters

retrieve_cash_drawer_shift

Provides the details for a single cash drawer shift, including all events that occurred during the shift.

Parameters

location_id (required)

The ID of the location to list cash drawer shifts for.

Type: string

shift_id (required)

The shift's ID.

Type: string

retrieve_catalog_object

Returns a single CatalogItem as a CatalogObject based on the provided ID. The returned object includes all of the relevant CatalogItem information including: CatalogItemVariation children, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.

Parameters

object_id (required)

The object ID of any type of CatalogObjects to be retrieved.

Type: string

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, its associated CatalogCategory, CatalogTaxes, CatalogImages and CatalogModifierLists will be returned in the related_objects field of the response. If the object field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the related_objects field of the response. Default value: false

Type: boolean

retrieve_customer

Returns details for a single customer.

Parameters

customer_id (required)

The ID of the customer to retrieve.

Type: string

retrieve_employee

Gets an Employee by Square-assigned employee ID (UUID)

Parameters

id (required)

UUID for the employee that was requested.

Type: string

retrieve_employee_role

Provides the details for a single employee role.

Parameters

role_id (required)

The role's ID.

Type: string

retrieve_inventory_adjustment

Returns the InventoryAdjustment object
with the provided adjustment_id.

Parameters

adjustment_id (required)

ID of the InventoryAdjustment to retrieve.

Type: string

retrieve_inventory_changes

Returns a set of physical counts and inventory adjustments for the provided CatalogObject at the requested Locations. 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.

Parameters

catalog_object_id (required)

ID of the CatalogObject to retrieve.

Type: string

location_ids

The Location IDs to look up as a comma-separated
list. An empty list queries all locations.

Type: string

retrieve_inventory_count

Retrieves the current calculated stock count for a given
CatalogObject at a given set of
Locations. Responses are paginated and unsorted.
For more sophisticated queries, use a batch endpoint.

Parameters

catalog_object_id (required)

ID of the CatalogObject to retrieve.

Type: string

location_ids

The Location IDs to look up as a comma-separated
list. An empty list queries all locations.

Type: string

retrieve_inventory_physical_count

Returns the InventoryPhysicalCount
object with the provided physical_count_id.

Parameters

physical_count_id (required)

ID of the
InventoryPhysicalCount to retrieve.

Type: string

retrieve_item

Provides the details for a single item, including associated modifier lists and fees.

Parameters

item_id (required)

The item's ID.

Type: string

location_id (required)

The ID of the item's associated location.

Type: string

retrieve_modifier_list

Provides the details for a single modifier list.

Parameters

location_id (required)

The ID of the item's associated location.

Type: string

modifier_list_id (required)

The modifier list's ID.

Type: string

retrieve_order

Provides comprehensive information for a single online store order, including the order's history.

Parameters

location_id (required)

The ID of the order's associated location.

Type: string

order_id (required)

The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint

Type: string

retrieve_payment

Provides comprehensive information for a single payment.

Parameters

location_id (required)

The ID of the payment's associated location.

Type: string

payment_id (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.

Type: string

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 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.

Parameters

location_id (required)

The ID of the settlements's associated location.

Type: string

settlement_id (required)

The settlement's Square-issued ID. You obtain this value from Settlement objects returned by the List Settlements endpoint.

Type: string

retrieve_timecard

Provides the details for a single timecard.

Only approved accounts can manage their employees with Square.
Unapproved accounts cannot use employee management features with the
API.

Parameters

timecard_id (required)

The timecard's ID.

Type: string

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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"access_token" : "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" : "The ID of the merchant whose token you want to revoke. Do not provide a value for access_token if you provide this parameter.",
"client_id" : "Your application's ID, available from the [application dashboard](https://connect.squareup.com/apps)."
}

search_catalog_objects

Queries the targeted catalog using a variety of query types: CatalogQuerySortedAttribute, CatalogQueryExact, CatalogQueryRange, CatalogQueryText, CatalogQueryItemsForTax, and CatalogQueryItemsForModifierList.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"cursor" : "The pagination cursor returned in the previous response. Leave unset for an initial request. See [Pagination](/basics/api101/pagination) for more information.",
"object_types" : [ "string" ],
"query" : {
"exact_query" : {
"attribute_name" : "The name of the attribute to be searched.",
"attribute_value" : "The desired value of the search attribute."
},
"text_query" : {
"keywords" : [ "string" ]
},
"items_for_tax_query" : {
"tax_ids" : [ "string" ]
},
"items_for_modifier_list_query" : {
"modifier_list_ids" : [ "string" ]
},
"items_for_item_options_query" : {
"item_option_ids" : [ "string" ]
},
"prefix_query" : {
"attribute_prefix" : "The desired prefix of the search attribute value.",
"attribute_name" : "The name of the attribute to be searched."
},
"range_query" : {
"attribute_max_value" : "The desired maximum value for the search attribute (inclusive).",
"attribute_name" : "The name of the attribute to be searched.",
"attribute_min_value" : "The desired minimum value for the search attribute (inclusive)."
},
"item_variations_for_item_option_values_query" : {
"item_option_value_ids" : [ "string" ]
},
"sorted_attribute_query" : {
"attribute_name" : "The attribute whose value should be used as the sort key.",
"initial_attribute_value" : "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" : "The desired [SortOrder](#type-sortorder), `\"ASC\"` (ascending) or `\"DESC\"` (descending). See [SortOrder](#type-sortorder) for possible values"
}
},
"limit" : "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.",
"begin_time" : "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.",
"include_related_objects" : "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.",
"include_deleted_objects" : "If `true`, deleted objects will be included in the results. Deleted objects will have their `is_deleted` field set to `true`."
}

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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"cursor" : "Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query. See [Pagination](/basics/api101/pagination) for more information.",
"query" : {
"filter" : {
"updated_at" : {
"end_at" : "A datetime value in RFC-3339 format indicating when the time range\nends.",
"start_at" : "A datetime value in RFC-3339 format indicating when the time range\nstarts."
},
"creation_source" : {
"values" : [ "string" ],
"rule" : "Indicates whether a customer profile matching the filter criteria should be included in the result or excluded from the result. Default: `INCLUDE`. See [CustomerInclusionExclusion](#type-customerinclusionexclusion) for possible values"
},
"created_at" : {
"end_at" : "A datetime value in RFC-3339 format indicating when the time range\nends.",
"start_at" : "A datetime value in RFC-3339 format indicating when the time range\nstarts."
}
},
"sort" : {
"field" : "The field to sort the results on. It could be the total money spent at the merchant, the date of the first visit (etc). See [CustomerSortField](#type-customersortfield) for possible values",
"order" : "Indicates the order in which results should be displayed based on the value of the sort field. String comparisons use standard alphabetic comparison to determine order. Strings representing numbers are sorted as strings. See [SortOrder](#type-sortorder) for possible values"
}
},
"limit" : "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."
}

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 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 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.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"cursor" : "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.",
"location_ids" : [ "string" ],
"query" : {
"filter" : {
"fulfillment_filter" : {
"fulfillment_states" : [ "string" ],
"fulfillment_types" : [ "string" ]
},
"state_filter" : {
"states" : [ "string" ]
},
"customer_filter" : {
"customer_ids" : [ "string" ]
},
"date_time_filter" : {
"closed_at" : {
"end_at" : "A datetime value in RFC-3339 format indicating when the time range\nends.",
"start_at" : "A datetime value in RFC-3339 format indicating when the time range\nstarts."
},
"updated_at" : {
"end_at" : "A datetime value in RFC-3339 format indicating when the time range\nends.",
"start_at" : "A datetime value in RFC-3339 format indicating when the time range\nstarts."
},
"created_at" : {
"end_at" : "A datetime value in RFC-3339 format indicating when the time range\nends.",
"start_at" : "A datetime value in RFC-3339 format indicating when the time range\nstarts."
}
},
"source_filter" : {
"source_names" : [ "string" ]
}
},
"sort" : {
"sort_field" : "The field to sort by. __Important:__ When using a [DateTimeFilter](#type-searchordersfilter), `sort_field` must match the timestamp field that the DateTimeFilter uses to filter. For example, If you set your `sort_field` to `CLOSED_AT` and you use a DateTimeFilter, your DateTimeFilter must filter for orders by their `CLOSED_AT` date. If this field does not match the timestamp field in `DateTimeFilter`, SearchOrders will return an error. Default: `CREATED_AT`. See [SearchOrdersSortField](#type-searchorderssortfield) for possible values",
"sort_order" : "The chronological order in which results are returned. Defaults to `DESC`. See [SortOrder](#type-sortorder) for possible values"
}
},
"limit" : "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 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`."
}

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
Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"cursor" : "opaque cursor for fetching the next page.",
"query" : {
"filter" : {
"workday" : {
"date_range" : {
"end_date" : "String in `YYYY-MM-DD` format, e.g. `2017-10-31` per the ISO 8601\nextended format for calendar dates.\nThe end of a date range (inclusive)",
"start_date" : "String in `YYYY-MM-DD` format, e.g. `2017-10-31` per the ISO 8601\nextended format for calendar dates.\nThe beginning of a date range (inclusive)"
},
"default_timezone" : "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.",
"match_shifts_by" : "The strategy on which the dates are applied. See [ShiftWorkdayMatcher](#type-shiftworkdaymatcher) for possible values"
},
"employee_id" : [ "string" ],
"start" : {
"end_at" : "A datetime value in RFC-3339 format indicating when the time range\nends.",
"start_at" : "A datetime value in RFC-3339 format indicating when the time range\nstarts."
},
"end" : {
"end_at" : "A datetime value in RFC-3339 format indicating when the time range\nends.",
"start_at" : "A datetime value in RFC-3339 format indicating when the time range\nstarts."
},
"location_id" : [ "string" ],
"status" : "Fetch a `Shift` instance by `Shift.status`.\nSee [ShiftFilterStatus](#type-shiftfilterstatus) for possible values"
},
"sort" : {
"field" : "The field to sort on.\nSee [ShiftSortField](#type-shiftsortfield) for possible values",
"order" : "The order in which results are returned. Defaults to DESC.\nSee [SortOrder](#type-sortorder) for possible values"
}
},
"limit" : "number of resources in a page (200 by default)."
}

update_break_type

Updates an existing BreakType.

Parameters

id (required)

UUID for the BreakType being updated.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"break_type" : {
"updated_at" : "A read-only timestamp in RFC 3339 format.",
"break_name" : "A human-readable name for this type of break. Will be displayed to\nemployees in Square products.",
"expected_duration" : "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthis break. Precision below minutes is truncated.",
"created_at" : "A read-only timestamp in RFC 3339 format.",
"id" : "UUID for this object.",
"is_paid" : "Whether this break counts towards time worked for compensation\npurposes.",
"version" : "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.",
"location_id" : "The ID of the business location this type of break applies to."
}
}

update_category

Modifies the details of an existing item category.

Parameters

category_id (required)

The ID of the category to edit.

Type: string

location_id (required)

The ID of the category's associated location.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"name" : "The category's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The category's unique ID."
}

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, then create a new one with the CreateCustomerCard endpoint.

Parameters

customer_id (required)

The ID of the customer to update.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"birthday" : "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.",
"note" : "An optional note to associate with the customer.",
"email_address" : "The customer's email address.",
"address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"reference_id" : "An optional second ID you can set to associate the customer with an\nentity in another system.",
"company_name" : "The name of the customer's company.",
"nickname" : "A nickname for the customer.",
"phone_number" : "The customer's phone number.",
"given_name" : "The customer's given (i.e., first) name.",
"family_name" : "The customer's family (i.e., last) name."
}

update_discount

Modifies the details of an existing discount.

Parameters

discount_id (required)

The ID of the discount to edit.

Type: string

location_id (required)

The ID of the category's associated location.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"pin_required" : "Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment.",
"color" : "The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See [V1DiscountColor](#type-v1discountcolor) for possible values",
"rate" : "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.",
"name" : "The discount's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"amount_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"id" : "The discount's unique ID.",
"discount_type" : "Indicates whether the discount is a FIXED value or entered at the time of sale. See [V1DiscountDiscountType](#type-v1discountdiscounttype) for possible values"
}

update_employee

Parameters

employee_id (required)

The ID of the role to modify.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"updated_at" : "The time when the employee entity was most recently updated, in ISO 8601 format.",
"last_name" : "The employee's last name.",
"created_at" : "The time when the employee entity was created, in ISO 8601 format.",
"external_id" : "An ID the merchant can set to associate the employee with an entity in another system.",
"id" : "The employee's unique ID.",
"first_name" : "The employee's first name.",
"role_ids" : [ "string" ],
"email" : "The employee's email address.",
"authorized_location_ids" : [ "string" ],
"status" : "CWhether the employee is ACTIVE or INACTIVE. Inactive employees cannot sign in to Square Register.Merchants update this field from the Square Dashboard. See [V1EmployeeStatus](#type-v1employeestatus) for possible values"
}

update_employee_role

Modifies the details of an employee role.

Parameters

role_id (required)

The ID of the role to modify.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"updated_at" : "The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated.",
"permissions" : [ "string" ],
"is_owner" : "If true, employees with this role have all permissions, regardless of the values indicated in permissions.",
"name" : "The role's merchant-defined name.",
"created_at" : "The time when the employee entity was created, in ISO 8601 format. Is set by Square when the Role is created.",
"id" : "The role's unique ID, Can only be set by Square."
}

update_fee

Modifies the details of an existing fee (tax).

Parameters

fee_id (required)

The ID of the fee to edit.

Type: string

location_id (required)

The ID of the fee's associated location.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"calculation_phase" : "Forthcoming See [V1FeeCalculationPhase](#type-v1feecalculationphase) for possible values",
"rate" : "The rate of the fee, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%.",
"name" : "The fee's name.",
"adjustment_type" : "The type of adjustment the fee applies to a payment. Currently, this value is TAX for all fees. See [V1FeeAdjustmentType](#type-v1feeadjustmenttype) for possible values",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The fee's unique ID.",
"inclusion_type" : "Whether the fee is ADDITIVE or INCLUSIVE. See [V1FeeInclusionType](#type-v1feeinclusiontype) for possible values",
"type" : "In countries with multiple classifications for sales taxes, indicates which classification the fee falls under. Currently relevant only to Canadian merchants. See [V1FeeType](#type-v1feetype) for possible values",
"applies_to_custom_amounts" : "If true, the fee applies to custom amounts entered into Square Register that are not associated with a particular item.",
"enabled" : "If true, the fee is applied to all appropriate items. If false, the fee is not applied at all."
}

update_item

Modifies the core details of an existing item.

Parameters

item_id (required)

The ID of the item to modify.

Type: string

location_id (required)

The ID of the item's associated location.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"master_image" : {
"id" : "The image's unique ID.",
"url" : "The image's publicly accessible URL."
},
"fees" : [ {
"calculation_phase" : "Forthcoming See [V1FeeCalculationPhase](#type-v1feecalculationphase) for possible values",
"rate" : "The rate of the fee, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%.",
"name" : "The fee's name.",
"adjustment_type" : "The type of adjustment the fee applies to a payment. Currently, this value is TAX for all fees. See [V1FeeAdjustmentType](#type-v1feeadjustmenttype) for possible values",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The fee's unique ID.",
"inclusion_type" : "Whether the fee is ADDITIVE or INCLUSIVE. See [V1FeeInclusionType](#type-v1feeinclusiontype) for possible values",
"type" : "In countries with multiple classifications for sales taxes, indicates which classification the fee falls under. Currently relevant only to Canadian merchants. See [V1FeeType](#type-v1feetype) for possible values",
"applies_to_custom_amounts" : "If true, the fee applies to custom amounts entered into Square Register that are not associated with a particular item.",
"enabled" : "If true, the fee is applied to all appropriate items. If false, the fee is not applied at all."
} ],
"color" : "The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See [V1ItemColor](#type-v1itemcolor) for possible values",
"visibility" : "Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See [V1ItemVisibility](#type-v1itemvisibility) for possible values",
"taxable" : "Deprecated. This field is not used.",
"description" : "The item's description.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"type" : "The item's type. This value is NORMAL for almost all items.\nSee [V1ItemType](#type-v1itemtype) for possible values",
"abbreviation" : "The text of the item's display label in Square Register. Only up to the first five characters of the string are used.",
"modifier_lists" : [ {
"selection_type" : "Indicates whether MULTIPLE options or a SINGLE option from the modifier list can be applied to a single item. See [V1ModifierListSelectionType](#type-v1modifierlistselectiontype) for possible values",
"name" : "The modifier list's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The modifier list's unique ID.",
"modifier_options" : [ {
"price_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"on_by_default" : "If true, the modifier option is the default option in a modifier list for which selection_type is SINGLE.",
"name" : "The modifier option's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The modifier option's unique ID.",
"modifier_list_id" : "The ID of the modifier list the option belongs to.",
"ordinal" : "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."
} ]
} ],
"category_id" : "The ID of the item's category, if any.",
"variations" : [ {
"pricing_type" : "Indicates whether the item variation's price is fixed or determined at the time of sale. See [V1VariationPricingType](#type-v1variationpricingtype) for possible values",
"price_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"item_id" : "The ID of the variation's associated item.",
"inventory_alert_threshold" : "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.",
"name" : "The item variation's name.",
"track_inventory" : "If true, inventory tracking is active for the variation.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The item variation's unique ID.",
"user_data" : "Arbitrary metadata associated with the variation. Cannot exceed 255 characters.",
"sku" : "The item variation's SKU, if any.",
"ordinal" : "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",
"inventory_alert_type" : "Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its inventory_alert_threshold. See [V1VariationInventoryAlertType](#type-v1variationinventoryalerttype) for possible values"
} ],
"name" : "The item's name.",
"id" : "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 (_).",
"category" : {
"name" : "The category's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The category's unique ID."
},
"available_online" : "If true, the item can be added to shipping orders from the merchant's online store.",
"available_for_pickup" : "If true, the item can be added to pickup orders from the merchant's online store. Default value: false"
}

update_item_modifier_lists

Updates the CatalogModifierList objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"modifier_lists_to_enable" : [ "string" ],
"item_ids" : [ "string" ],
"modifier_lists_to_disable" : [ "string" ]
}

update_item_taxes

Updates the CatalogTax objects that apply to the
targeted CatalogItem without having to perform an
upsert on the entire item.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"item_ids" : [ "string" ],
"taxes_to_disable" : [ "string" ],
"taxes_to_enable" : [ "string" ]
}

update_modifier_list

Modifies the details of an existing item modifier list.

Parameters

location_id (required)

The ID of the item's associated location.

Type: string

modifier_list_id (required)

The ID of the modifier list to edit.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"selection_type" : "Indicates whether multiple options from the modifier list can be applied to a single item. See [V1UpdateModifierListRequestSelectionType](#type-v1updatemodifierlistrequestselectiontype) for possible values",
"name" : "The modifier list's name."
}

update_modifier_option

Modifies the details of an existing item modifier option.

Parameters

location_id (required)

The ID of the item's associated location.

Type: string

modifier_list_id (required)

The ID of the modifier list to edit.

Type: string

modifier_option_id (required)

The ID of the modifier list to edit.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"price_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"on_by_default" : "If true, the modifier option is the default option in a modifier list for which selection_type is SINGLE.",
"name" : "The modifier option's name.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The modifier option's unique ID.",
"modifier_list_id" : "The ID of the modifier list the option belongs to.",
"ordinal" : "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."
}

update_order

Updates an open 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 containing only the fields to update and the version the update is being applied to. - If deleting fields, the dot notation paths identifying fields to clear. To pay for an order, please refer to the Pay for Orders guide. To learn more about the Orders API, see the Orders API Overview.

Parameters

location_id (required)

The ID of the location to list refunds for.

Type: string

order_id (required)

The ID of the order to list refunds for.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"fields_to_clear" : [ "string" ],
"idempotency_key" : "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](/basics/api101/idempotency) for more information.",
"order" : {
"reference_id" : "A client specified identifier to associate an entity in another system with this order.",
"taxes" : [ {
"uid" : "Unique ID that identifies the tax only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogTax](#type-catalogtax).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"percentage" : "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%.",
"scope" : "Indicates the level at which the tax applies. For `ORDER` scoped taxes, Square generates references in `applied_taxes` on all order line items that do not have them. For `LINE_ITEM` scoped taxes, the tax will only apply to line items with references in their `applied_taxes` field. This field is immutable. To change the scope, you must delete the tax and re-add it as a new tax. See [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values",
"name" : "The tax's name.",
"type" : "Indicates the calculation method used to apply the tax. See [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values"
} ],
"created_at" : "Timestamp for when the order was created. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\".",
"source" : {
"name" : "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."
},
"line_items" : [ {
"quantity_unit" : {
"precision" : "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.",
"measurement_unit" : {
"volume_unit" : "Represents a standard volume unit. See [MeasurementUnitVolume](#type-measurementunitvolume) for possible values",
"weight_unit" : "Represents a standard unit of weight or mass. See [MeasurementUnitWeight](#type-measurementunitweight) for possible values",
"generic_unit" : "Reserved for API integrations that lack the ability to specify a real measurement unit See [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values",
"area_unit" : "Represents a standard area unit. See [MeasurementUnitArea](#type-measurementunitarea) for possible values",
"type" : "Represents the type of the measurement unit. See [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values",
"custom_unit" : {
"name" : "The name of the custom unit, for example \"bushel\".",
"abbreviation" : "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears in the cart for the Point of Sale app, and in reports."
},
"length_unit" : "Represents a standard length unit. See [MeasurementUnitLength](#type-measurementunitlength) for possible values"
}
},
"note" : "The note of the line item.",
"catalog_object_id" : "The [CatalogItemVariation](#type-catalogitemvariation) id applied to this line item.",
"quantity" : "The quantity purchased, formatted as a decimal number.\nFor example: `\"3\"`.\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example: `\"1.70000\"`.",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"variation_name" : "The name of the variation applied to this line item.",
"modifiers" : [ {
"uid" : "Unique ID that identifies the modifier only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogModifier](#type-catalogmodifier).",
"total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The name of the item modifier."
} ],
"gross_sales_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"uid" : "Unique ID that identifies the line item only within this order.",
"variation_total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The name of the line item.",
"total_discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ],
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_discounts" : [ {
"uid" : "Unique ID that identifies the applied discount only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"discount_uid" : "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`."
} ]
} ],
"location_id" : "The ID of the merchant location this order is associated with.",
"refunds" : [ {
"transaction_id" : "The ID of the transaction that the refunded tender is part of.",
"reason" : "The reason for the refund being issued.",
"tender_id" : "The ID of the refunded tender.",
"created_at" : "The time when the refund was created, in RFC 3339 format.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"id" : "The refund's unique ID.",
"processing_fee_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"additional_recipients" : [ {
"receivable_id" : "The unique ID for this [AdditionalRecipientReceivable](#type-additionalrecipientreceivable), assigned by the server.",
"description" : "The description of the additional recipient.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"location_id" : "The location ID for a recipient (other than the merchant) receiving a portion of this tender."
} ],
"location_id" : "The ID of the refund's associated location.",
"status" : "The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`,\nor `FAILED`).\nSee [RefundStatus](#type-refundstatus) for possible values"
} ],
"fulfillments" : [ {
"uid" : "Unique ID that identifies the fulfillment only within this order.",
"pickup_details" : {
"note" : "A note meant to provide additional instructions about the pickup fulfillment displayed in the Square Point of Sale and set by the API.",
"schedule_type" : "The schedule type of the pickup fulfillment. Defaults to `SCHEDULED`. See [OrderFulfillmentPickupDetailsScheduleType](#type-orderfulfillmentpickupdetailsscheduletype) for possible values",
"rejected_at" : "The [timestamp](#workingwithdates) indicating when the fulfillment was rejected. In RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"pickup_at" : "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.",
"canceled_at" : "The [timestamp](#workingwithdates) in RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\", indicating when the fulfillment was canceled.",
"pickup_window_duration" : "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.",
"expired_at" : "The [timestamp](#workingwithdates) indicating when the fulfillment expired. In RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"placed_at" : "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" : "The [timestamp](#workingwithdates) indicating when the fulfillment\nwas accepted. In RFC3339 timestamp format,\ne.g., \"2016-09-04T23:59:33.123Z\".",
"cancel_reason" : "A description of why the pickup was canceled. Max length: 100 characters.",
"expires_at" : "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.",
"ready_at" : "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\".",
"picked_up_at" : "The [timestamp](#workingwithdates) indicating when the fulfillment\nwas picked up by the recipient. In RFC3339 timestamp format,\ne.g., \"2016-09-04T23:59:33.123Z\".",
"recipient" : {
"email_address" : "The email address of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"phone_number" : "The phone number of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"customer_id" : "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" : "The display name of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`."
},
"auto_complete_duration" : "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.",
"prep_time_duration" : "The duration of time it takes to prepare this fulfillment.\nMust be in RFC3339 duration format, e.g., \"P1W3D\"."
},
"shipment_details" : {
"packaged_at" : "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\".",
"shipped_at" : "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\".",
"shipping_note" : "A note with additional information for the shipping carrier.",
"expected_shipped_at" : "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\".",
"canceled_at" : "The [timestamp](#workingwithdates) indicating the shipment was canceled. Must be in RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"shipping_type" : "A description of the type of shipping product purchased from the carrier. e.g. First Class, Priority, Express",
"in_progress_at" : "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\".",
"failure_reason" : "A description of why the shipment failed to be completed.",
"placed_at" : "The [timestamp](#workingwithdates) indicating when the shipment was requested. Must be in RFC3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".",
"carrier" : "The shipping carrier being used to ship this fulfillment\ne.g. UPS, FedEx, USPS, etc.",
"cancel_reason" : "A description of why the shipment was canceled.",
"recipient" : {
"email_address" : "The email address of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"phone_number" : "The phone number of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`.",
"customer_id" : "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" : "The display name of the fulfillment recipient. If provided, overrides the value pulled from the customer profile indicated by `customer_id`."
},
"tracking_number" : "The reference number provided by the carrier to track the shipment's progress.",
"failed_at" : "The [timestamp](#workingwithdates) indicating when the shipment\nfailed to be completed. Must be in RFC3339 timestamp format, e.g.,\n\"2016-09-04T23:59:33.123Z\".",
"tracking_url" : "A link to the tracking webpage on the carrier's website."
},
"state" : "The state of the fulfillment. See [OrderFulfillmentState](#type-orderfulfillmentstate) for possible values",
"type" : "The type of the fulfillment. See [OrderFulfillmentType](#type-orderfulfillmenttype) for possible values"
} ],
"discounts" : [ {
"uid" : "Unique ID that identifies the discount only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogDiscount](#type-catalogdiscount).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"percentage" : "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.",
"scope" : "Indicates the level at which the discount applies. For `ORDER` scoped discounts, Square generates references in `applied_discounts` on all order line items that do not have them. For `LINE_ITEM` scoped discounts, the discount only applies to line items with a discount reference in their `applied_discounts` field. This field is immutable. To change the scope of a discount you must delete the discount and re-add it as a new discount. See [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values",
"name" : "The discount's name.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"type" : "The type of the discount. If it is created by API, it would be either `FIXED_PERCENTAGE` or `FIXED_AMOUNT`. VARIABLE_* is not supported in API because the order is created at the time of sale and either percentage or amount has to be specified. See [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values"
} ],
"updated_at" : "Timestamp for when the order was last updated. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\".",
"total_discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"net_amounts" : {
"discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"id" : "The order's unique ID.",
"state" : "The current state of the order. `OPEN`,`COMPLETED`,`CANCELED`\nSee [OrderState](#type-orderstate) for possible values",
"rounding_adjustment" : {
"uid" : "Unique ID that identifies the rounding adjustment only within this order.",
"name" : "The name of the rounding adjustment from the original sale Order.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"closed_at" : "Timestamp for when the order was closed. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\".",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charges" : [ {
"uid" : "Unique ID that identifies the service charge only within this order.",
"catalog_object_id" : "The catalog object ID referencing the service charge [CatalogObject](#type-catalogobject).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"calculation_phase" : "The calculation phase at which to apply the service charge. See [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"taxable" : "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.",
"percentage" : "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.",
"name" : "The name of the service charge.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ]
} ],
"version" : "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](/orders-api/manage-orders#update-orders).",
"tenders" : [ {
"transaction_id" : "The ID of the tender's associated transaction.",
"card_details" : {
"entry_method" : "The method used to enter the card's details for the transaction. See [TenderCardDetailsEntryMethod](#type-tendercarddetailsentrymethod) for possible values",
"card" : {
"last_4" : "The last 4 digits of the card number.",
"card_brand" : "The card's brand (such as `VISA`).\nSee [CardBrand](#type-cardbrand) for possible values",
"fingerprint" : "A unique, Square-assigned ID that identifies the card across multiple locations and applications for a single Square account.",
"exp_month" : "The expiration month of the associated card as an integer between 1 and 12.",
"billing_address" : {
"country" : "The address's country, in ISO 3166-1-alpha-2 format.\nSee [Country](#type-country) for possible values",
"administrative_district_level_3" : "A civil entity within the address's `administrative_district_level_2`, if any.",
"locality" : "The city or town of the address.",
"sublocality" : "A civil region within the address's `locality`, if any.",
"last_name" : "Optional last name when it's representing recipient.",
"administrative_district_level_2" : "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.",
"administrative_district_level_1" : "A civil entity within the address's country. In the US, this\nis the state.",
"sublocality_3" : "A civil region within the address's `sublocality_2`, if any.",
"sublocality_2" : "A civil region within the address's `sublocality`, if any.",
"organization" : "Optional organization name when it's representing recipient.",
"address_line_1" : "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_3" : "The third line of the address, if any.",
"address_line_2" : "The second line of the address, if any.",
"postal_code" : "The address's postal code.",
"first_name" : "Optional first name when it's representing recipient."
},
"id" : "Unique ID for this card. Generated by Square.",
"exp_year" : "The four-digit year of the card's expiration date.",
"cardholder_name" : "The name of the cardholder."
},
"status" : "The credit card payment's current state (such as `AUTHORIZED` or `CAPTURED`). See [TenderCardDetailsStatus](#type-tendercarddetailsstatus) for possible values"
},
"note" : "An optional note associated with the tender at the time of payment.",
"created_at" : "The time when the tender was created, in RFC 3339 format.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"type" : "The type of tender, such as `CARD` or `CASH`.\nSee [TenderType](#type-tendertype) for possible values",
"processing_fee_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"location_id" : "The ID of the transaction's associated location.",
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"payment_id" : "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.",
"cash_details" : {
"buyer_tendered_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"change_back_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"id" : "The tender's unique ID.",
"customer_id" : "If the tender is associated with a customer or represents a customer's card on file, this is the ID of the associated customer.",
"additional_recipients" : [ {
"receivable_id" : "The unique ID for this [AdditionalRecipientReceivable](#type-additionalrecipientreceivable), assigned by the server.",
"description" : "The description of the additional recipient.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"location_id" : "The location ID for a recipient (other than the merchant) receiving a portion of this tender."
} ]
} ],
"return_amounts" : {
"discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"returns" : [ {
"uid" : "Unique ID that identifies the return only within this order.",
"return_line_items" : [ {
"quantity_unit" : {
"precision" : "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.",
"measurement_unit" : {
"volume_unit" : "Represents a standard volume unit. See [MeasurementUnitVolume](#type-measurementunitvolume) for possible values",
"weight_unit" : "Represents a standard unit of weight or mass. See [MeasurementUnitWeight](#type-measurementunitweight) for possible values",
"generic_unit" : "Reserved for API integrations that lack the ability to specify a real measurement unit See [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values",
"area_unit" : "Represents a standard area unit. See [MeasurementUnitArea](#type-measurementunitarea) for possible values",
"type" : "Represents the type of the measurement unit. See [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values",
"custom_unit" : {
"name" : "The name of the custom unit, for example \"bushel\".",
"abbreviation" : "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears in the cart for the Point of Sale app, and in reports."
},
"length_unit" : "Represents a standard length unit. See [MeasurementUnitLength](#type-measurementunitlength) for possible values"
}
},
"note" : "The note of the returned line item.",
"catalog_object_id" : "The [CatalogItemVariation](#type-catalogitemvariation) id applied to this returned line item.",
"source_line_item_uid" : "`uid` of the LineItem in the original sale Order.",
"quantity" : "The quantity returned, formatted as a decimal number.\nFor example: `\"3\"`.\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example: `\"1.70000\"`.",
"gross_return_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"variation_name" : "The name of the variation applied to this returned line item.",
"uid" : "Unique identifier for this return line item entry.",
"variation_total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"return_modifiers" : [ {
"uid" : "Unique ID that identifies the return modifier only within this order.",
"source_modifier_uid" : "`uid` of the Modifier from the LineItem from the Order which contains the original sale of this line item modifier.",
"catalog_object_id" : "The catalog object id referencing [CatalogModifier](#type-catalogmodifier).",
"total_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"base_price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The name of the item modifier."
} ],
"name" : "The name of the line item.",
"total_discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ],
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_discounts" : [ {
"uid" : "Unique ID that identifies the applied discount only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"discount_uid" : "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`."
} ]
} ],
"rounding_adjustment" : {
"uid" : "Unique ID that identifies the rounding adjustment only within this order.",
"name" : "The name of the rounding adjustment from the original sale Order.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"return_amounts" : {
"discount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tip_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"service_charge_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
}
},
"source_order_id" : "Order which contains the original sale of these returned line items. This will be unset for unlinked returns.",
"return_service_charges" : [ {
"uid" : "Unique ID that identifies the return service charge only within this order.",
"catalog_object_id" : "The catalog object ID of the associated [CatalogServiceCharge](#type-catalogservicecharge).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"calculation_phase" : "The calculation phase after which to apply the service charge. See [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values",
"total_tax_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"taxable" : "Indicates whether the surcharge can be taxed. Service charges\ncalculated in the `TOTAL_PHASE` cannot be marked as taxable.",
"percentage" : "The percentage of the service charge, as a string representation of\na decimal number. For example, a value of `\"7.25\"` corresponds to a\npercentage of 7.25%.\nExactly one of `percentage` or `amount_money` should be set.",
"name" : "The name of the service charge.",
"source_service_charge_uid" : "`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.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"applied_taxes" : [ {
"uid" : "Unique ID that identifies the applied tax only within this order.",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"tax_uid" : "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."
} ]
} ],
"return_discounts" : [ {
"uid" : "Unique ID that identifies the return discount only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogDiscount](#type-catalogdiscount).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"source_discount_uid" : "`uid` of the Discount from the Order which contains the original application of this discount.",
"percentage" : "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.",
"scope" : "Indicates the level at which the `OrderReturnDiscount` applies. For `ORDER` scoped discounts, the server will generate references in `applied_discounts` on all `OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the discount will only apply to `OrderReturnLineItem`s with references in their `applied_discounts` field. See [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values",
"name" : "The discount's name.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"type" : "The type of the discount. If it is created by API, it would be either `FIXED_PERCENTAGE` or `FIXED_AMOUNT`. VARIABLE_* is not supported in API because the order is created at the time of sale and either percentage or amount has to be specified. See [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values"
} ],
"return_taxes" : [ {
"uid" : "Unique ID that identifies the return tax only within this order.",
"catalog_object_id" : "The catalog object id referencing [CatalogTax](#type-catalogtax).",
"applied_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"percentage" : "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%.",
"scope" : "Indicates the level at which the `OrderReturnTax` applies. For `ORDER` scoped taxes, Square generates references in `applied_taxes` on all `OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax will only apply to `OrderReturnLineItem`s with references in their `applied_discounts` field. See [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values",
"source_tax_uid" : "`uid` of the Tax from the Order which contains the original charge of this tax.",
"name" : "The tax's name.",
"type" : "Indicates the calculation method used to apply the tax. See [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values"
} ]
} ],
"total_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"customer_id" : "The [Customer](#type-customer) ID of the customer associated with the order."
}
}

update_page

Modifies the details of a Favorites page in Square Register.

Parameters

location_id (required)

The ID of the Favorites page's associated location

Type: string

page_id (required)

The ID of the page to modify.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"cells" : [ {
"page_id" : "The unique identifier of the page the cell is included on.",
"object_type" : "The type of entity represented in the cell (ITEM, DISCOUNT, CATEGORY, or PLACEHOLDER). See [V1PageCellObjectType](#type-v1pagecellobjecttype) for possible values",
"placeholder_type" : "For a cell with an object_type of PLACEHOLDER, this value indicates the cell's special behavior. See [V1PageCellPlaceholderType](#type-v1pagecellplaceholdertype) for possible values",
"column" : "The column of the cell. Always an integer between 0 and 4, inclusive.",
"row" : "The row of the cell. Always an integer between 0 and 4, inclusive.",
"object_id" : "The unique identifier of the entity represented in the cell. Not present for cells with an object_type of PLACEHOLDER."
} ],
"page_index" : "The page's position in the merchant's list of pages. Always an integer between 0 and 6, inclusive.",
"name" : "The page's name, if any.",
"id" : "The page's unique identifier."
}

update_page_cell

Modifies a cell of a Favorites page in Square Register.

Parameters

location_id (required)

The ID of the Favorites page's associated location.

Type: string

page_id (required)

The ID of the page the cell belongs to.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"page_id" : "The unique identifier of the page the cell is included on.",
"object_type" : "The type of entity represented in the cell (ITEM, DISCOUNT, CATEGORY, or PLACEHOLDER). See [V1PageCellObjectType](#type-v1pagecellobjecttype) for possible values",
"placeholder_type" : "For a cell with an object_type of PLACEHOLDER, this value indicates the cell's special behavior. See [V1PageCellPlaceholderType](#type-v1pagecellplaceholdertype) for possible values",
"column" : "The column of the cell. Always an integer between 0 and 4, inclusive.",
"row" : "The row of the cell. Always an integer between 0 and 4, inclusive.",
"object_id" : "The unique identifier of the entity represented in the cell. Not present for cells with an object_type of PLACEHOLDER."
}

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.

Parameters

id (required)

ID of the object being updated.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"shift" : {
"end_at" : "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).",
"breaks" : [ {
"end_at" : "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" : "The `BreakType` this `Break` was templated on.",
"name" : "A human-readable name.",
"expected_duration" : "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthe break.",
"id" : "UUID for this object",
"is_paid" : "Whether this break counts towards time worked for compensation\npurposes.",
"start_at" : "RFC 3339; follows same timezone info as `Shift`. Precision up to\nthe minute is respected; seconds are truncated."
} ],
"updated_at" : "A read-only timestamp in RFC 3339 format; presented in UTC.",
"timezone" : "Read-only convenience value that is calculated from the location based on `location_id`. Format: the IANA Timezone Database identifier for the location timezone.",
"employee_id" : "The ID of the employee this shift belongs to.",
"created_at" : "A read-only timestamp in RFC 3339 format; presented in UTC.",
"id" : "UUID for this object",
"start_at" : "RFC 3339; shifted to location timezone + offset. Precision up to the\nminute is respected; seconds are truncated.",
"version" : "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.",
"location_id" : "The ID of the location this shift occurred at. Should be based on\nwhere the employee clocked in.",
"wage" : {
"hourly_rate" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"title" : "The name of the job performed during this shift. Square\nlabor-reporting UIs may group shifts together by title."
},
"status" : "Describes working state of the current `Shift`.\nSee [ShiftStatus](#type-shiftstatus) for possible values"
}
}

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.

Parameters

timecard_id (required)

TThe ID of the timecard to modify.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"deleted" : "If true, the timecard was deleted by the merchant, and it is no longer valid.",
"doubletime_seconds_worked" : "The total number of doubletime seconds worked in the timecard.",
"updated_at" : "The time when the timecard was most recently updated, in ISO 8601 format.",
"clockin_time" : "The clock-in time for the timecard, in ISO 8601 format.",
"employee_id" : "The ID of the employee the timecard is associated with.",
"overtime_seconds_worked" : "The total number of overtime seconds worked in the timecard.",
"clockin_location_id" : "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.",
"created_at" : "The time when the timecard was created, in ISO 8601 format.",
"clockout_time" : "The clock-out time for the timecard, in ISO 8601 format. Provide this value only if importing timecard information from another system.",
"id" : "The timecard's unique ID.",
"regular_seconds_worked" : "The total number of regular (non-overtime) seconds worked in the timecard.",
"clockout_location_id" : "The ID of the location the employee clocked out from. Provide this value only if importing timecard information from another system."
}

update_variation

Modifies the details of an existing item variation.

Parameters

item_id (required)

The ID of the item to modify.

Type: string

location_id (required)

The ID of the item's associated location.

Type: string

variation_id (required)

The ID of the variation to modify.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"pricing_type" : "Indicates whether the item variation's price is fixed or determined at the time of sale. See [V1VariationPricingType](#type-v1variationpricingtype) for possible values",
"price_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"item_id" : "The ID of the variation's associated item.",
"inventory_alert_threshold" : "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.",
"name" : "The item variation's name.",
"track_inventory" : "If true, inventory tracking is active for the variation.",
"v2_id" : "The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.",
"id" : "The item variation's unique ID.",
"user_data" : "Arbitrary metadata associated with the variation. Cannot exceed 255 characters.",
"sku" : "The item variation's SKU, if any.",
"ordinal" : "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",
"inventory_alert_type" : "Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its inventory_alert_threshold. See [V1VariationInventoryAlertType](#type-v1variationinventoryalerttype) for possible values"
}

update_workweek_config

Updates a WorkweekConfig.

Parameters

id (required)

UUID for the WorkweekConfig object being updated.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"workweek_config" : {
"start_of_week" : "The day of the week on which a business week cuts over for\ncompensation purposes.\nSee [Weekday](#type-weekday) for possible values",
"updated_at" : "A read-only timestamp in RFC 3339 format; presented in UTC",
"created_at" : "A read-only timestamp in RFC 3339 format; presented in UTC",
"id" : "UUID for this object",
"start_of_day_local_time" : "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" : "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."
}
}

upsert_catalog_object

Creates or updates the target CatalogObject.

Parameters

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"idempotency_key" : "A value you specify that uniquely identifies this\nrequest among all your requests. A common way to create\na valid idempotency key is to use a Universally unique\nidentifier (UUID).\nIf you're unsure whether a particular request was successful,\nyou can reattempt it with the same idempotency key without\nworrying about creating duplicate objects.\nSee [Idempotency](/basics/api101/idempotency) for more information.",
"object" : {
"category_data" : {
"name" : "The category's name. Searchable. This field has max length of 255 Unicode code points."
},
"measurement_unit_data" : {
"precision" : "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",
"measurement_unit" : {
"volume_unit" : "Represents a standard volume unit. See [MeasurementUnitVolume](#type-measurementunitvolume) for possible values",
"weight_unit" : "Represents a standard unit of weight or mass. See [MeasurementUnitWeight](#type-measurementunitweight) for possible values",
"generic_unit" : "Reserved for API integrations that lack the ability to specify a real measurement unit See [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values",
"area_unit" : "Represents a standard area unit. See [MeasurementUnitArea](#type-measurementunitarea) for possible values",
"type" : "Represents the type of the measurement unit. See [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values",
"custom_unit" : {
"name" : "The name of the custom unit, for example \"bushel\".",
"abbreviation" : "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears in the cart for the Point of Sale app, and in reports."
},
"length_unit" : "Represents a standard length unit. See [MeasurementUnitLength](#type-measurementunitlength) for possible values"
}
},
"discount_data" : {
"pin_required" : "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" : "The color of the discount's display label in the Square Point of Sale app. This must be a valid hex color code.",
"percentage" : "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.",
"name" : "The discount's name. Searchable. This field has max length of 255 Unicode code points.",
"amount_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"discount_type" : "Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale. See [CatalogDiscountType](#type-catalogdiscounttype) for possible values"
},
"item_option_value_data" : {
"item_option_id" : "Unique ID of the associated item option.",
"color" : "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.",
"name" : "Name of this item option value. Searchable.",
"description" : "The option value's human-readable description.",
"item_variation_count" : "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.",
"ordinal" : "Determines where this option value appears in a list of option values."
},
"catalog_v1_ids" : [ {
"location_id" : "The ID of the [location](#type-location) this Connect V1 ID is associated with.",
"catalog_v1_id" : "The ID for an object in Connect V1, if different from its Connect V2 ID."
} ],
"absent_at_location_ids" : [ "string" ],
"modifier_list_data" : {
"selection_type" : "Indicates whether multiple options from the [CatalogModifierList](#type-catalogmodifierlist) can be applied to a single [CatalogItem](#type-catalogitem). See [CatalogModifierListSelectionType](#type-catalogmodifierlistselectiontype) for possible values",
"name" : "The [CatalogModifierList](#type-catalogmodifierlist)'s name. Searchable. This field has max length of 255 Unicode code points.",
"modifiers" : [ "CatalogObject" ]
},
"type" : "The type of this object. Each object type has expected properties expressed in a structured format within its corresponding `*_data` field below. See [CatalogObjectType](#type-catalogobjecttype) for possible values",
"version" : "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.",
"present_at_location_ids" : [ "string" ],
"tax_data" : {
"calculation_phase" : "Whether the tax is calculated based on a payment's subtotal or total. See [TaxCalculationPhase](#type-taxcalculationphase) for possible values",
"percentage" : "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%.",
"name" : "The tax's name. Searchable. This field has max length of 255 Unicode code points.",
"inclusion_type" : "Whether the tax is `ADDITIVE` or `INCLUSIVE`.\nSee [TaxInclusionType](#type-taxinclusiontype) for possible values",
"applies_to_custom_amounts" : "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" : "If `true`, the tax will be shown as enabled in the Square Point of Sale app."
},
"item_data" : {
"item_options" : [ {
"item_option_id" : "The unique id of the item option, used to form the dimensions of the item option matrix in a specified order."
} ],
"tax_ids" : [ "string" ],
"label_color" : "The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code.",
"description" : "The item's description. Searchable. This field has max length of 4096 Unicode code points.",
"modifier_list_info" : [ {
"max_selected_modifiers" : "If zero or larger, the largest number of [CatalogModifier](#type-catalogmodifier)s that can be selected from this [CatalogModifierList](#type-catalogmodifierlist).",
"modifier_list_id" : "The ID of the [CatalogModifierList](#type-catalogmodifierlist) controlled by this [CatalogModifierListInfo](#type-catalogmodifierlistinfo).",
"modifier_overrides" : [ {
"on_by_default" : "If `true`, this [CatalogModifier](#type-catalogmodifier) should be selected by default for this [CatalogItem](#type-catalogitem).",
"modifier_id" : "The ID of the [CatalogModifier](#type-catalogmodifier) whose default behavior is being overridden."
} ],
"enabled" : "If `true`, enable this [CatalogModifierList](#type-catalogmodifierlist).",
"min_selected_modifiers" : "If zero or larger, the smallest number of [CatalogModifier](#type-catalogmodifier)s that must be selected from this [CatalogModifierList](#type-catalogmodifierlist)."
} ],
"abbreviation" : "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.",
"available_electronically" : "If `true`, the item can be added to electronically fulfilled orders from the merchant's online store.",
"product_type" : "The product type of the item. May not be changed once an item has been created. Only items of product type `REGULAR` or `APPOINTMENTS_SERVICE` may be created by this API; items with other product types are read-only. See [CatalogItemProductType](#type-catalogitemproducttype) for possible values",
"category_id" : "The ID of the item's category, if any.",
"variations" : [ "CatalogObject" ],
"name" : "The item's name. Searchable. This field must not be empty. This field has max length of 512 Unicode code points.",
"skip_modifier_screen" : "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.",
"available_online" : "If `true`, the item can be added to shipping orders from the merchant's online store.",
"available_for_pickup" : "If `true`, the item can be added to pickup orders from the merchant's online store."
},
"present_at_all_locations" : "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`.",
"product_set_data" : {
"product_ids_all" : [ "string" ],
"all_products" : "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.",
"quantity_min" : "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.",
"name" : "User-defined name for the product set. For example, \"Clearance Items\"\nor \"Winter Sale Items\".",
"quantity_exact" : "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_max" : "If set, the pricing rule will apply to a maximum of this many items from `products_any` or `products_all`.",
"product_ids_any" : [ "string" ]
},
"is_deleted" : "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.",
"updated_at" : "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.",
"item_variation_data" : {
"item_option_values" : [ {
"item_option_id" : "The unique id of an item option.",
"item_option_value_id" : "The unique id of the selected value for the item option."
} ],
"price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"item_id" : "The ID of the [CatalogItem](#type-catalogitem) associated with this item variation. Searchable.",
"upc" : "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.",
"location_overrides" : [ {
"pricing_type" : "The pricing type (fixed or variable) for the [CatalogItemVariation](#type-catalogitemvariation) at the given [location](#type-location). See [CatalogPricingType](#type-catalogpricingtype) for possible values",
"price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"inventory_alert_threshold" : "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.",
"track_inventory" : "If `true`, inventory tracking is active for the [CatalogItemVariation](#type-catalogitemvariation) at this [location](#type-location).",
"location_id" : "The ID of the [location](#type-location).",
"inventory_alert_type" : "Indicates whether the [CatalogItemVariation](#type-catalogitemvariation) displays an alert when its inventory quantity is less than or equal to its `inventory_alert_threshold`. See [InventoryAlertType](#type-inventoryalerttype) for possible values"
} ],
"user_data" : "Arbitrary user metadata to associate with the item variation. Cannot exceed 255 characters. Searchable.",
"service_duration" : "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).",
"pricing_type" : "Indicates whether the item variation's price is fixed or determined at the time of sale. See [CatalogPricingType](#type-catalogpricingtype) for possible values",
"inventory_alert_threshold" : "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.",
"measurement_unit_id" : "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.",
"name" : "The item variation's name. Searchable. This field has max length of 255 Unicode code points.",
"track_inventory" : "If `true`, inventory tracking is active for the variation.",
"sku" : "The item variation's SKU, if any. Searchable.",
"ordinal" : "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.",
"inventory_alert_type" : "Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its `inventory_alert_threshold`. See [InventoryAlertType](#type-inventoryalerttype) for possible values"
},
"time_period_data" : {
"event" : "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."
},
"image_data" : {
"name" : "The internal name of this image. Identifies this image in calls to the Connect APIs.",
"caption" : "A caption that describes what is shown in the image. Displayed in the Square Online Store.",
"url" : "The URL of this image. Generated by Square after an image is uploaded to the CreateCatalogImage endpoint."
},
"item_option_data" : {
"item_count" : "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`.",
"values" : [ "CatalogObject" ],
"name" : "The item option's display name for the seller. Must be unique across\nall item options. Searchable.",
"description" : "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" : "If true, display colors for entries in `values` when present.",
"display_name" : "The item option's display name for the customer. Searchable."
},
"id" : "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.",
"image_id" : "Identifies the `CatalogImage` attached to this `CatalogObject`.",
"pricing_rule_data" : {
"time_period_ids" : [ "string" ],
"exclude_products_id" : "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_until_date" : "Represents the date the pricing rule will become inactive.\nRepresented in RFC3339 full-date format (YYYY-MM-DD).",
"name" : "User-defined name for the pricing rule. For example, \"Buy one get one free\" or \"10% off\".",
"apply_products_id" : "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.",
"match_products_id" : "Unique ID for the [CatalogProductSet](#type-catalogproductset) that will be matched by this rule. A match rule matches within the entire cart.",
"valid_from_date" : "Represents the date the Pricing Rule is valid from. Represented in\nRFC3339 full-date format (YYYY-MM-DD).",
"valid_from_local_time" : "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_local_time" : "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.",
"discount_id" : "Unique ID for the [CatalogDiscount](#type-catalogdiscount) to take off the price of all matched items. Only one of `total_price_money`, `item_price`, or `discount` can be supplied."
},
"modifier_data" : {
"price_money" : {
"amount" : "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" : "The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](#type-currency) for possible values. See [Currency](#type-currency) for possible values"
},
"name" : "The modifier's name. Searchable. This field has max length of 255 Unicode code points."
}
}
}

v1_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.

Parameters

location_id (required)

The ID of the original payment's associated location.

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"reason" : "The reason for the refund.",
"request_idempotence_key" : "An optional key to ensure idempotence if you issue the same PARTIAL refund request more than once.",
"payment_id" : "The ID of the payment to refund. If you are creating a `PARTIAL`\nrefund for a split tender payment, instead provide the id of the\nparticular tender you want to refund.",
"refunded_money" : {
"amount" : "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" : "See [Currency](#type-currency) for possible values"
},
"type" : "TThe type of refund (FULL or PARTIAL). See [V1CreateRefundRequestType](#type-v1createrefundrequesttype) for possible values"
}

v1_list_employees

Provides summary information for all of a business's employees.

Parameters

batch_token

A pagination cursor to retrieve the next set of results for your
original query to the endpoint.

Type: string

begin_created_at

If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format.

Type: string

begin_updated_at

If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format

Type: string

end_created_at

If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format.

Type: string

end_updated_at

If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format.

Type: string

external_id

If provided, the endpoint returns only employee entities with the specified external_id.

Type: string

limit

The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.

Type: integer

order

The order in which employees are listed in the response, based on their created_at field. Default value: ASC

Type: string

status

If provided, the endpoint returns only employee entities with the specified status (ACTIVE or INACTIVE).

Type: string

v1_list_locations

This operation has no parameters

v1_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.

Parameters

location_id (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.

Type: string

batch_token

A pagination cursor to retrieve the next set of results for your
original query to the endpoint.

Type: string

begin_time

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.

Type: string

end_time

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.

Type: string

include_partial

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.

Type: boolean

limit

The maximum number of payments to return in a single response. This value cannot exceed 200.

Type: integer

order

The order in which payments are listed in the response.

Type: string

v1_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.

Parameters

location_id (required)

The ID of the location to list refunds for.

Type: string

batch_token

A pagination cursor to retrieve the next set of results for your
original query to the endpoint.

Type: string

begin_time

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.

Type: string

end_time

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.

Type: string

limit

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.

Type: integer

order

TThe order in which payments are listed in the response.

Type: string

v1_retrieve_employee

Provides the details for a single employee.

Parameters

employee_id (required)

The employee's ID.

Type: string

v1_update_order

Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:

Parameters

location_id (required)

The ID of the order's associated location.

Type: string

order_id (required)

The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint

Type: string

$body

An object containing the fields to POST for the request.
See the corresponding object definition for field details.

Type: object

{
"completed_note" : "A merchant-specified note about the completion of the order. Only valid if action is COMPLETE.",
"canceled_note" : "A merchant-specified note about the canceling of the order. Only valid if action is CANCEL.",
"shipped_tracking_number" : "The tracking number of the shipment associated with the order. Only valid if action is COMPLETE.",
"action" : "The action to perform on the order (COMPLETE, CANCEL, or REFUND). See [V1UpdateOrderRequestAction](#type-v1updateorderrequestaction) for possible values",
"refunded_note" : "A merchant-specified note about the refunding of the order. Only valid if action is REFUND."
}