Square Model Context Protocol Server

/** * Property definition in a type */ interface TypeProperty { /** Property name */ name: string; /** Property type */ type: string; /** Property description */ description: string; /** Whether the property is read-only */ readOnly: boolean; /** Whether the property is required */ required: boolean; /** Array item type (if property is an array) */ arrayType?: string; /** Whether this property represents a file path */ isFile?: boolean; } /** * Type definition */ interface TypeDefinition { /** Type name */ name: string; /** Type properties */ properties: TypeProperty[]; } /** * Type map */ interface TypeMap { /** Type definitions by request type */ [key: string]: TypeDefinition[]; } /** * Type map for all Square API request types */ export const typeMap: TypeMap = { "RegisterDomainRequest": [ { "name": "RegisterDomainRequest", "properties": [ { "name": "domain_name", "type": "string", "description": "A domain name as described in RFC-1034 that will be registered with ApplePay.", "readOnly": false, "required": true } ] } ], "ListBankAccountsRequest": [ { "name": "ListBankAccountsRequest", "properties": [ { "name": "cursor", "type": "string", "description": "The pagination cursor returned by a previous call to this endpoint.\nUse it in the next `ListBankAccounts` request to retrieve the next set \nof results.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "Upper limit on the number of bank accounts to return in the response. \nCurrently, 1000 is the largest supported limit. You can specify a limit \nof up to 1000 bank accounts. This is also the default limit.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "Location ID. You can specify this optional filter \nto retrieve only the linked bank accounts belonging to a specific location.", "readOnly": false, "required": false } ] } ], "GetBankAccountByV1IdRequest": [ { "name": "GetBankAccountByV1IdRequest", "properties": [ { "name": "v1_bank_account_id", "type": "string", "description": "Connect V1 ID of the desired `BankAccount`. For more information, see \n[Retrieve a bank account by using an ID issued by V1 Bank Accounts API](https://developer.squareup.com/docs/bank-accounts-api#retrieve-a-bank-account-by-using-an-id-issued-by-v1-bank-accounts-api).", "readOnly": false, "required": true } ] } ], "GetBankAccountRequest": [ { "name": "GetBankAccountRequest", "properties": [ { "name": "bank_account_id", "type": "string", "description": "Square-issued ID of the desired `BankAccount`.", "readOnly": false, "required": true } ] } ], "ListBookingCustomAttributeDefinitionsRequest": [ { "name": "ListBookingCustomAttributeDefinitionsRequest", "properties": [ { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] } ], "CreateBookingCustomAttributeDefinitionRequest": [ { "name": "CreateBookingCustomAttributeDefinitionRequest", "properties": [ { "name": "custom_attribute_definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "The custom attribute definition to create, with the following fields:\n\n- `key`\n\n- `name`. If provided, `name` must be unique (case-sensitive) across all visible booking-related custom attribute\ndefinitions for the seller.\n\n- `description`\n\n- `visibility`. Note that all custom attributes are visible in exported booking data, including those set to\n`VISIBILITY_HIDDEN`.\n\n- `schema`. With the exception of the `Selection` data type, the `schema` is specified as a\nsimple URL to the JSON schema definition hosted on the Square CDN. For more information, see\n[Specifying the schema](https://developer.squareup.com/docs/booking-custom-attributes-api/custom-attribute-definitions#specify-schema).", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false } ] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] } ], "DeleteBookingCustomAttributeDefinitionRequest": [ { "name": "DeleteBookingCustomAttributeDefinitionRequest", "properties": [ { "name": "key", "type": "string", "description": "The key of the custom attribute definition to delete.", "readOnly": false, "required": true } ] } ], "RetrieveBookingCustomAttributeDefinitionRequest": [ { "name": "RetrieveBookingCustomAttributeDefinitionRequest", "properties": [ { "name": "version", "type": "integer", "description": "The current version of the custom attribute definition, which is used for strongly consistent\nreads to guarantee that you receive the most up-to-date data. When included in the request,\nSquare returns the specified version or a higher version if one exists. If the specified version\nis higher than the current version, Square returns a `BAD_REQUEST` error.", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "The key of the custom attribute definition to retrieve. If the requesting application\nis not the definition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "UpdateBookingCustomAttributeDefinitionRequest": [ { "name": "UpdateBookingCustomAttributeDefinitionRequest", "properties": [ { "name": "custom_attribute_definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "The custom attribute definition that contains the fields to update. Only the following fields can be updated:\n- `name`\n- `description`\n- `visibility`\n- `schema` for a `Selection` data type. Only changes to the named options or the maximum number of allowed\nselections are supported.\n\nFor more information, see\n[Updatable definition fields](https://developer.squareup.com/docs/booking-custom-attributes-api/custom-attribute-definitions#updatable-definition-fields).\n\nTo enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol, include the optional `version` field and specify the current version of the custom attribute definition.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "The key of the custom attribute definition to update.", "readOnly": false, "required": true } ] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] } ], "BulkDeleteBookingCustomAttributesRequest": [ { "name": "BulkDeleteBookingCustomAttributesRequest", "properties": [ { "name": "values", "type": "map", "description": "A map containing 1 to 25 individual Delete requests. For each request, provide an\narbitrary ID that is unique for this `BulkDeleteBookingCustomAttributes` request and the\ninformation needed to delete a custom attribute.", "readOnly": false, "required": true } ] } ], "BulkUpsertBookingCustomAttributesRequest": [ { "name": "BulkUpsertBookingCustomAttributesRequest", "properties": [ { "name": "values", "type": "map", "description": "A map containing 1 to 25 individual upsert requests. For each request, provide an\narbitrary ID that is unique for this `BulkUpsertBookingCustomAttributes` request and the\ninformation needed to create or update a custom attribute.", "readOnly": false, "required": true } ] } ], "ListBookingCustomAttributesRequest": [ { "name": "ListBookingCustomAttributesRequest", "properties": [ { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request. For more\ninformation, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "with_definitions", "type": "boolean", "description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each\ncustom attribute. Set this parameter to `true` to get the name and description of each custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "readOnly": false, "required": false }, { "name": "booking_id", "type": "string", "description": "The ID of the target [booking](entity:Booking).", "readOnly": false, "required": true } ] } ], "DeleteBookingCustomAttributeRequest": [ { "name": "DeleteBookingCustomAttributeRequest", "properties": [ { "name": "booking_id", "type": "string", "description": "The ID of the target [booking](entity:Booking).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to delete. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "RetrieveBookingCustomAttributeRequest": [ { "name": "RetrieveBookingCustomAttributeRequest", "properties": [ { "name": "with_definition", "type": "boolean", "description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of\nthe custom attribute. Set this parameter to `true` to get the name and description of the custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The current version of the custom attribute, which is used for strongly consistent reads to\nguarantee that you receive the most up-to-date data. When included in the request, Square\nreturns the specified version or a higher version if one exists. If the specified version is\nhigher than the current version, Square returns a `BAD_REQUEST` error.", "readOnly": false, "required": false }, { "name": "booking_id", "type": "string", "description": "The ID of the target [booking](entity:Booking).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to retrieve. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "UpsertBookingCustomAttributeRequest": [ { "name": "UpsertBookingCustomAttributeRequest", "properties": [ { "name": "custom_attribute", "type": "#/components/schemas/CustomAttribute", "description": "The custom attribute to create or update, with the following fields:\n\n- `value`. This value must conform to the `schema` specified by the definition.\nFor more information, see [Value data types](https://developer.squareup.com/docs/booking-custom-attributes-api/custom-attributes#value-data-types).\n\n- `version`. To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol for an update operation, include this optional field and specify the current version\nof the custom attribute.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "booking_id", "type": "string", "description": "The ID of the target [booking](entity:Booking).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to create or update. This key must match the `key` of a\ncustom attribute definition in the Square seller account. If the requesting application is not\nthe definition owner, you must use the qualified key.", "readOnly": false, "required": true } ] }, { "name": "CustomAttribute", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).", "readOnly": false, "required": false }, { "name": "value", "type": "string", "description": "The value assigned to the custom attribute. It is validated against the custom\nattribute definition's schema on write operations. For more information about custom\nattribute values,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute. This field is incremented when the custom attribute is changed.\nWhen updating an existing custom attribute value, you can provide this field\nand specify the current version of the custom attribute to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "A copy of the `visibility` field value for the associated custom attribute definition.\n", "readOnly": true, "required": false }, { "name": "definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "A copy of the associated custom attribute definition object. This field is only set when\nthe optional field is specified on the request.", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute was created or was most recently\nupdated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "ListBookingsRequest": [ { "name": "ListBookingsRequest", "properties": [ { "name": "limit", "type": "integer", "description": "The maximum number of results per page to return in a paged response.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The [customer](entity:Customer) for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved.", "readOnly": false, "required": false }, { "name": "team_member_id", "type": "string", "description": "The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved.", "readOnly": false, "required": false }, { "name": "start_at_min", "type": "string", "description": "The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "start_at_max", "type": "string", "description": "The RFC 3339 timestamp specifying the latest of the start time. If this is not set, the time of 31 days after `start_at_min` is used.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false } ] } ], "CreateBookingRequest": [ { "name": "CreateBookingRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique key to make this request an idempotent operation.", "readOnly": false, "required": false }, { "name": "booking", "type": "#/components/schemas/Booking", "description": "The details of the booking to be created.", "readOnly": false, "required": true } ] }, { "name": "Booking", "properties": [ { "name": "id", "type": "string", "description": "A unique ID of this object representing a booking.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "The revision number for the booking used for optimistic concurrency.", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/BookingStatus", "description": "The status of the booking, describing where the booking stands with respect to the booking state machine.\n", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The RFC 3339 timestamp specifying the creation time of this booking.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The RFC 3339 timestamp specifying the most recent update time of this booking.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "start_at", "type": "string", "description": "The RFC 3339 timestamp specifying the starting time of this booking.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the [Location](entity:Location) object representing the location where the booked service is provided. Once set when the booking is created, its value cannot be changed.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the [Customer](entity:Customer) object representing the customer receiving the booked service.", "readOnly": false, "required": false }, { "name": "customer_note", "type": "string", "description": "The free-text field for the customer to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a relevant [CatalogObject](entity:CatalogObject) instance.", "readOnly": false, "required": false }, { "name": "seller_note", "type": "string", "description": "The free-text field for the seller to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a specific [CatalogObject](entity:CatalogObject) instance.\nThis field should not be visible to customers.", "readOnly": false, "required": false }, { "name": "appointment_segments", "type": "array", "description": "A list of appointment segments for this booking.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/AppointmentSegment" }, { "name": "transition_time_minutes", "type": "integer", "description": "Additional time at the end of a booking.\nApplications should not make this field visible to customers of a seller.", "readOnly": true, "required": false }, { "name": "all_day", "type": "boolean", "description": "Whether the booking is of a full business day.", "readOnly": true, "required": false }, { "name": "location_type", "type": "#/components/schemas/BusinessAppointmentSettingsBookingLocationType", "description": "The type of location where the booking is held.\n", "readOnly": false, "required": false }, { "name": "creator_details", "type": "#/components/schemas/BookingCreatorDetails", "description": "Information about the booking creator.", "readOnly": true, "required": false }, { "name": "source", "type": "#/components/schemas/BookingBookingSource", "description": "The source of the booking.\nAccess to this field requires seller-level permissions.\n", "readOnly": true, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "Stores a customer address if the location type is `CUSTOMER_LOCATION`.", "readOnly": false, "required": false } ] }, { "name": "BookingStatus", "properties": [] }, { "name": "AppointmentSegment", "properties": [ { "name": "duration_minutes", "type": "integer", "description": "The time span in minutes of an appointment segment.", "readOnly": false, "required": false }, { "name": "service_variation_id", "type": "string", "description": "The ID of the [CatalogItemVariation](entity:CatalogItemVariation) object representing the service booked in this segment.", "readOnly": false, "required": false }, { "name": "team_member_id", "type": "string", "description": "The ID of the [TeamMember](entity:TeamMember) object representing the team member booked in this segment.", "readOnly": false, "required": true }, { "name": "service_variation_version", "type": "integer", "description": "The current version of the item variation representing the service booked in this segment.", "readOnly": false, "required": false }, { "name": "intermission_minutes", "type": "integer", "description": "Time between the end of this segment and the beginning of the subsequent segment.", "readOnly": true, "required": false }, { "name": "any_team_member", "type": "boolean", "description": "Whether the customer accepts any team member, instead of a specific one, to serve this segment.", "readOnly": true, "required": false }, { "name": "resource_ids", "type": "array", "description": "The IDs of the seller-accessible resources used for this appointment segment.", "readOnly": true, "required": false } ] }, { "name": "BusinessAppointmentSettingsBookingLocationType", "properties": [] }, { "name": "BookingCreatorDetails", "properties": [ { "name": "creator_type", "type": "#/components/schemas/BookingCreatorDetailsCreatorType", "description": "The seller-accessible type of the creator of the booking.\n", "readOnly": true, "required": false }, { "name": "team_member_id", "type": "string", "description": "The ID of the team member who created the booking, when the booking creator is of the `TEAM_MEMBER` type.\nAccess to this field requires seller-level permissions.", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the customer who created the booking, when the booking creator is of the `CUSTOMER` type.\nAccess to this field requires seller-level permissions.", "readOnly": true, "required": false } ] }, { "name": "BookingCreatorDetailsCreatorType", "properties": [] }, { "name": "BookingBookingSource", "properties": [] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] } ], "SearchAvailabilityRequest": [ { "name": "SearchAvailabilityRequest", "properties": [ { "name": "query", "type": "#/components/schemas/SearchAvailabilityQuery", "description": "Query conditions used to filter buyer-accessible booking availabilities.", "readOnly": false, "required": true } ] }, { "name": "SearchAvailabilityQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/SearchAvailabilityFilter", "description": "The query filter to search for buyer-accessible availabilities of existing bookings.", "readOnly": false, "required": true } ] }, { "name": "SearchAvailabilityFilter", "properties": [ { "name": "start_at_range", "type": "#/components/schemas/TimeRange", "description": "The query expression to search for buy-accessible availabilities with their starting times falling within the specified time range.\nThe time range must be at least 24 hours and at most 32 days long.\nFor waitlist availabilities, the time range can be 0 or more up to 367 days long.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The query expression to search for buyer-accessible availabilities with their location IDs matching the specified location ID.\nThis query expression cannot be set if `booking_id` is set.", "readOnly": false, "required": false }, { "name": "segment_filters", "type": "array", "description": "The query expression to search for buyer-accessible availabilities matching the specified list of segment filters.\nIf the size of the `segment_filters` list is `n`, the search returns availabilities with `n` segments per availability.\n\nThis query expression cannot be set if `booking_id` is set.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/SegmentFilter" }, { "name": "booking_id", "type": "string", "description": "The query expression to search for buyer-accessible availabilities for an existing booking by matching the specified `booking_id` value.\nThis is commonly used to reschedule an appointment.\nIf this expression is set, the `location_id` and `segment_filters` expressions cannot be set.", "readOnly": false, "required": false } ] }, { "name": "TimeRange", "properties": [ { "name": "start_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nstarts.", "readOnly": false, "required": false }, { "name": "end_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nends.", "readOnly": false, "required": false } ] }, { "name": "SegmentFilter", "properties": [ { "name": "service_variation_id", "type": "string", "description": "The ID of the [CatalogItemVariation](entity:CatalogItemVariation) object representing the service booked in this segment.", "readOnly": false, "required": true }, { "name": "team_member_id_filter", "type": "#/components/schemas/FilterValue", "description": "A query filter to search for buyer-accessible appointment segments with service-providing team members matching the specified list of team member IDs. Supported query expressions are\n- `ANY`: return the appointment segments with team members whose IDs match any member in this list.\n- `NONE`: return the appointment segments with team members whose IDs are not in this list.\n- `ALL`: not supported.\n\nWhen no expression is specified, any service-providing team member is eligible to fulfill the Booking.", "readOnly": false, "required": false } ] }, { "name": "FilterValue", "properties": [ { "name": "all", "type": "array", "description": "A list of terms that must be present on the field of the resource.", "readOnly": false, "required": false }, { "name": "any", "type": "array", "description": "A list of terms where at least one of them must be present on the\nfield of the resource.", "readOnly": false, "required": false }, { "name": "none", "type": "array", "description": "A list of terms that must not be present on the field the resource", "readOnly": false, "required": false } ] } ], "BulkRetrieveBookingsRequest": [ { "name": "BulkRetrieveBookingsRequest", "properties": [ { "name": "booking_ids", "type": "array", "description": "A non-empty list of [Booking](entity:Booking) IDs specifying bookings to retrieve.", "readOnly": false, "required": true } ] } ], "RetrieveBusinessBookingProfileRequest": [ { "name": "RetrieveBusinessBookingProfileRequest", "properties": [] } ], "ListLocationBookingProfilesRequest": [ { "name": "ListLocationBookingProfilesRequest", "properties": [ { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a paged response.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.", "readOnly": false, "required": false } ] } ], "RetrieveLocationBookingProfileRequest": [ { "name": "RetrieveLocationBookingProfileRequest", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the location to retrieve the booking profile.", "readOnly": false, "required": true } ] } ], "ListTeamMemberBookingProfilesRequest": [ { "name": "ListTeamMemberBookingProfilesRequest", "properties": [ { "name": "bookable_only", "type": "boolean", "description": "Indicates whether to include only bookable team members in the returned result (`true`) or not (`false`).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a paged response.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "Indicates whether to include only team members enabled at the given location in the returned result.", "readOnly": false, "required": false } ] } ], "BulkRetrieveTeamMemberBookingProfilesRequest": [ { "name": "BulkRetrieveTeamMemberBookingProfilesRequest", "properties": [ { "name": "team_member_ids", "type": "array", "description": "A non-empty list of IDs of team members whose booking profiles you want to retrieve.", "readOnly": false, "required": true } ] } ], "RetrieveTeamMemberBookingProfileRequest": [ { "name": "RetrieveTeamMemberBookingProfileRequest", "properties": [ { "name": "team_member_id", "type": "string", "description": "The ID of the team member to retrieve.", "readOnly": false, "required": true } ] } ], "RetrieveBookingRequest": [ { "name": "RetrieveBookingRequest", "properties": [ { "name": "booking_id", "type": "string", "description": "The ID of the [Booking](entity:Booking) object representing the to-be-retrieved booking.", "readOnly": false, "required": true } ] } ], "UpdateBookingRequest": [ { "name": "UpdateBookingRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique key to make this request an idempotent operation.", "readOnly": false, "required": false }, { "name": "booking", "type": "#/components/schemas/Booking", "description": "The booking to be updated. Individual attributes explicitly specified here override the corresponding values of the existing booking.", "readOnly": false, "required": true }, { "name": "booking_id", "type": "string", "description": "The ID of the [Booking](entity:Booking) object representing the to-be-updated booking.", "readOnly": false, "required": true } ] }, { "name": "Booking", "properties": [ { "name": "id", "type": "string", "description": "A unique ID of this object representing a booking.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "The revision number for the booking used for optimistic concurrency.", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/BookingStatus", "description": "The status of the booking, describing where the booking stands with respect to the booking state machine.\n", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The RFC 3339 timestamp specifying the creation time of this booking.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The RFC 3339 timestamp specifying the most recent update time of this booking.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "start_at", "type": "string", "description": "The RFC 3339 timestamp specifying the starting time of this booking.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the [Location](entity:Location) object representing the location where the booked service is provided. Once set when the booking is created, its value cannot be changed.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the [Customer](entity:Customer) object representing the customer receiving the booked service.", "readOnly": false, "required": false }, { "name": "customer_note", "type": "string", "description": "The free-text field for the customer to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a relevant [CatalogObject](entity:CatalogObject) instance.", "readOnly": false, "required": false }, { "name": "seller_note", "type": "string", "description": "The free-text field for the seller to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a specific [CatalogObject](entity:CatalogObject) instance.\nThis field should not be visible to customers.", "readOnly": false, "required": false }, { "name": "appointment_segments", "type": "array", "description": "A list of appointment segments for this booking.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/AppointmentSegment" }, { "name": "transition_time_minutes", "type": "integer", "description": "Additional time at the end of a booking.\nApplications should not make this field visible to customers of a seller.", "readOnly": true, "required": false }, { "name": "all_day", "type": "boolean", "description": "Whether the booking is of a full business day.", "readOnly": true, "required": false }, { "name": "location_type", "type": "#/components/schemas/BusinessAppointmentSettingsBookingLocationType", "description": "The type of location where the booking is held.\n", "readOnly": false, "required": false }, { "name": "creator_details", "type": "#/components/schemas/BookingCreatorDetails", "description": "Information about the booking creator.", "readOnly": true, "required": false }, { "name": "source", "type": "#/components/schemas/BookingBookingSource", "description": "The source of the booking.\nAccess to this field requires seller-level permissions.\n", "readOnly": true, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "Stores a customer address if the location type is `CUSTOMER_LOCATION`.", "readOnly": false, "required": false } ] }, { "name": "BookingStatus", "properties": [] }, { "name": "AppointmentSegment", "properties": [ { "name": "duration_minutes", "type": "integer", "description": "The time span in minutes of an appointment segment.", "readOnly": false, "required": false }, { "name": "service_variation_id", "type": "string", "description": "The ID of the [CatalogItemVariation](entity:CatalogItemVariation) object representing the service booked in this segment.", "readOnly": false, "required": false }, { "name": "team_member_id", "type": "string", "description": "The ID of the [TeamMember](entity:TeamMember) object representing the team member booked in this segment.", "readOnly": false, "required": true }, { "name": "service_variation_version", "type": "integer", "description": "The current version of the item variation representing the service booked in this segment.", "readOnly": false, "required": false }, { "name": "intermission_minutes", "type": "integer", "description": "Time between the end of this segment and the beginning of the subsequent segment.", "readOnly": true, "required": false }, { "name": "any_team_member", "type": "boolean", "description": "Whether the customer accepts any team member, instead of a specific one, to serve this segment.", "readOnly": true, "required": false }, { "name": "resource_ids", "type": "array", "description": "The IDs of the seller-accessible resources used for this appointment segment.", "readOnly": true, "required": false } ] }, { "name": "BusinessAppointmentSettingsBookingLocationType", "properties": [] }, { "name": "BookingCreatorDetails", "properties": [ { "name": "creator_type", "type": "#/components/schemas/BookingCreatorDetailsCreatorType", "description": "The seller-accessible type of the creator of the booking.\n", "readOnly": true, "required": false }, { "name": "team_member_id", "type": "string", "description": "The ID of the team member who created the booking, when the booking creator is of the `TEAM_MEMBER` type.\nAccess to this field requires seller-level permissions.", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the customer who created the booking, when the booking creator is of the `CUSTOMER` type.\nAccess to this field requires seller-level permissions.", "readOnly": true, "required": false } ] }, { "name": "BookingCreatorDetailsCreatorType", "properties": [] }, { "name": "BookingBookingSource", "properties": [] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] } ], "CancelBookingRequest": [ { "name": "CancelBookingRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique key to make this request an idempotent operation.", "readOnly": false, "required": false }, { "name": "booking_version", "type": "integer", "description": "The revision number for the booking used for optimistic concurrency.", "readOnly": false, "required": false }, { "name": "booking_id", "type": "string", "description": "The ID of the [Booking](entity:Booking) object representing the to-be-cancelled booking.", "readOnly": false, "required": true } ] } ], "ListCardsRequest": [ { "name": "ListCardsRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for your original query.\n\nSee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "Limit results to cards associated with the customer supplied.\nBy default, all cards owned by the merchant are returned.", "readOnly": false, "required": false }, { "name": "include_disabled", "type": "boolean", "description": "Includes disabled cards.\nBy default, all enabled cards owned by the merchant are returned.", "readOnly": false, "required": false }, { "name": "reference_id", "type": "string", "description": "Limit results to cards associated with the reference_id supplied.", "readOnly": false, "required": false }, { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "Sorts the returned list by when the card was created with the specified order.\nThis field defaults to ASC.\n", "readOnly": false, "required": false } ] }, { "name": "SortOrder", "properties": [] } ], "CreateCardRequest": [ { "name": "CreateCardRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this CreateCard request. Keys can be\nany valid string and must be unique for every request.\n\nMax: 45 characters\n\nSee [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information.", "readOnly": false, "required": true }, { "name": "source_id", "type": "string", "description": "The ID of the source which represents the card information to be stored. This can be a card nonce or a payment id.", "readOnly": false, "required": true }, { "name": "verification_token", "type": "string", "description": "An identifying token generated by [Payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).\nVerification tokens encapsulate customer device information and 3-D Secure\nchallenge results to indicate that Square has verified the buyer identity.\n\nSee the [SCA Overview](https://developer.squareup.com/docs/sca-overview).", "readOnly": false, "required": false }, { "name": "card", "type": "#/components/schemas/Card", "description": "Payment details associated with the card to be stored.", "readOnly": false, "required": true } ] }, { "name": "Card", "properties": [ { "name": "id", "type": "string", "description": "Unique ID for this card. Generated by Square.", "readOnly": true, "required": false }, { "name": "card_brand", "type": "#/components/schemas/CardBrand", "description": "The card's brand.\n", "readOnly": true, "required": false }, { "name": "last_4", "type": "string", "description": "The last 4 digits of the card number.", "readOnly": true, "required": false }, { "name": "exp_month", "type": "integer", "description": "The expiration month of the associated card as an integer between 1 and 12.", "readOnly": false, "required": false }, { "name": "exp_year", "type": "integer", "description": "The four-digit year of the card's expiration date.", "readOnly": false, "required": false }, { "name": "cardholder_name", "type": "string", "description": "The name of the cardholder.", "readOnly": false, "required": false }, { "name": "billing_address", "type": "#/components/schemas/Address", "description": "The billing address for this card.", "readOnly": false, "required": false }, { "name": "fingerprint", "type": "string", "description": "Intended as a Square-assigned identifier, based\non the card number, to identify the card across multiple locations within a\nsingle application.", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "**Required** The ID of a customer created using the Customers API to be associated with the card.", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the merchant associated with the card.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional user-defined reference ID that associates this card with\nanother entity in an external system. For example, a customer ID from an\nexternal customer management system.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "Indicates whether or not a card can be used for payments.", "readOnly": true, "required": false }, { "name": "card_type", "type": "#/components/schemas/CardType", "description": "The type of the card.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "prepaid_type", "type": "#/components/schemas/CardPrepaidType", "description": "Indicates whether the Card is prepaid or not.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "bin", "type": "string", "description": "The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API\nreturns this field.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "Current version number of the card. Increments with each card update. Requests to update an\nexisting Card object will be rejected unless the version in the request matches the current\nversion for the Card.", "readOnly": false, "required": false }, { "name": "card_co_brand", "type": "#/components/schemas/CardCoBrand", "description": "The card's co-brand if available. For example, an Afterpay virtual card would have a\nco-brand of AFTERPAY.\n", "readOnly": true, "required": false } ] }, { "name": "CardBrand", "properties": [] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "CardType", "properties": [] }, { "name": "CardPrepaidType", "properties": [] }, { "name": "CardCoBrand", "properties": [] } ], "RetrieveCardRequest": [ { "name": "RetrieveCardRequest", "properties": [ { "name": "card_id", "type": "string", "description": "Unique ID for the desired Card.", "readOnly": false, "required": true } ] } ], "DisableCardRequest": [ { "name": "DisableCardRequest", "properties": [ { "name": "card_id", "type": "string", "description": "Unique ID for the desired Card.", "readOnly": false, "required": true } ] } ], "ListCashDrawerShiftsRequest": [ { "name": "ListCashDrawerShiftsRequest", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the location to query for a list of cash drawer shifts.", "readOnly": false, "required": true }, { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "The order in which cash drawer shifts are listed in the response,\nbased on their opened_at field. Default value: ASC\n", "readOnly": false, "required": false }, { "name": "begin_time", "type": "string", "description": "The inclusive start time of the query on opened_at, in ISO 8601 format.", "readOnly": false, "required": false }, { "name": "end_time", "type": "string", "description": "The exclusive end date of the query on opened_at, in ISO 8601 format.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "Number of cash drawer shift events in a page of results (200 by\ndefault, 1000 max).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "Opaque cursor for fetching the next page of results.", "readOnly": false, "required": false } ] }, { "name": "SortOrder", "properties": [] } ], "RetrieveCashDrawerShiftRequest": [ { "name": "RetrieveCashDrawerShiftRequest", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the location to retrieve cash drawer shifts from.", "readOnly": false, "required": true }, { "name": "shift_id", "type": "string", "description": "The shift ID.", "readOnly": false, "required": true } ] } ], "ListCashDrawerShiftEventsRequest": [ { "name": "ListCashDrawerShiftEventsRequest", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the location to list cash drawer shifts for.", "readOnly": false, "required": true }, { "name": "limit", "type": "integer", "description": "Number of resources to be returned in a page of results (200 by\ndefault, 1000 max).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "Opaque cursor for fetching the next page of results.", "readOnly": false, "required": false }, { "name": "shift_id", "type": "string", "description": "The shift ID.", "readOnly": false, "required": true } ] } ], "BatchDeleteCatalogObjectsRequest": [ { "name": "BatchDeleteCatalogObjectsRequest", "properties": [ { "name": "object_ids", "type": "array", "description": "The IDs of the CatalogObjects to be deleted. When an object is deleted, other objects\nin the graph that depend on that object will be deleted as well (for example, deleting a\nCatalogItem will delete its CatalogItemVariation.", "readOnly": false, "required": false } ] } ], "BatchRetrieveCatalogObjectsRequest": [ { "name": "BatchRetrieveCatalogObjectsRequest", "properties": [ { "name": "object_ids", "type": "array", "description": "The IDs of the CatalogObjects to be retrieved.", "readOnly": false, "required": true }, { "name": "include_related_objects", "type": "boolean", "description": "If `true`, the response will include additional objects that are related to the\nrequested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field\nof the response. These objects are put in the `related_objects` field. Setting this to `true` is\nhelpful when the objects are needed for immediate display to a user.\nThis process only goes one level deep. Objects referenced by the related objects will not be included. For example,\n\nif the `objects` field of the response contains a CatalogItem, its associated\nCatalogCategory objects, CatalogTax objects, CatalogImage objects and\nCatalogModifierLists will be returned in the `related_objects` field of the\nresponse. If the `objects` field of the response contains a CatalogItemVariation,\nits parent CatalogItem will be returned in the `related_objects` field of\nthe response.\n\nDefault value: `false`", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The specific version of the catalog objects to be included in the response. \nThis allows you to retrieve historical versions of objects. The specified version value is matched against\nthe [CatalogObject](entity:CatalogObject)s' `version` attribute. If not included, results will\nbe from the current version of the catalog.", "readOnly": false, "required": false }, { "name": "include_deleted_objects", "type": "boolean", "description": "Indicates whether to include (`true`) or not (`false`) in the response deleted objects, namely, those with the `is_deleted` attribute set to `true`.", "readOnly": false, "required": false }, { "name": "include_category_path_to_root", "type": "boolean", "description": "Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists\nof `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category\nand ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned\nin the response payload.", "readOnly": false, "required": false } ] } ], "BatchUpsertCatalogObjectsRequest": [ { "name": "BatchUpsertCatalogObjectsRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "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).\n\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.\n\nSee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information.", "readOnly": false, "required": true }, { "name": "batches", "type": "array", "description": "A batch of CatalogObjects to be inserted/updated atomically.\nThe objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs\nattempting to insert or update an object within a batch, the entire batch will be rejected. However, an error\nin one batch will not affect other batches within the same request.\n\nFor each object, its `updated_at` field is ignored and replaced with a current [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates), and its\n`is_deleted` field must not be set to `true`.\n\nTo modify an existing object, supply its ID. To create a new object, use an ID starting\nwith `#`. These IDs may be used to create relationships between an object and attributes of\nother objects that reference it. For example, you can create a CatalogItem with\nID `#ABC` and a CatalogItemVariation with its `item_id` attribute set to\n`#ABC` in order to associate the CatalogItemVariation with its parent\nCatalogItem.\n\nAny `#`-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs.\n\nEach batch may contain up to 1,000 objects. The total number of objects across all batches for a single request\nmay not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will\nbe inserted or updated.", "readOnly": false, "required": true, "arrayType": "#/components/schemas/CatalogObjectBatch" } ] }, { "name": "CatalogObjectBatch", "properties": [ { "name": "objects", "type": "array", "description": "A list of CatalogObjects belonging to this batch.", "readOnly": false, "required": true, "arrayType": "#/components/schemas/CatalogObject" } ] }, { "name": "CatalogObject", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogObjectType", "description": "The type of this object. Each object type has expected\nproperties expressed in a structured format within its corresponding `*_data` field below.\n", "readOnly": false, "required": true }, { "name": "id", "type": "string", "description": "An identifier to reference this object in the catalog. When a new `CatalogObject`\nis inserted, the client should set the id to a temporary identifier starting with\na \"`#`\" character. Other objects being inserted or updated within the same request\nmay use this identifier to refer to the new object.\n\nWhen the server receives the new object, it will supply a unique identifier that\nreplaces the temporary identifier for all future references.", "readOnly": false, "required": true }, { "name": "updated_at", "type": "string", "description": "Last modification [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) in RFC 3339 format, e.g., `\"2016-08-15T23:59:33.123Z\"`\nwould indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "The version of the object. When updating an object, the version supplied\nmust match the version in the database, otherwise the write will be rejected as conflicting.", "readOnly": false, "required": false }, { "name": "is_deleted", "type": "boolean", "description": "If `true`, the object has been deleted from the database. Must be `false` for new objects\nbeing inserted. When deleted, the `updated_at` field will equal the deletion time.", "readOnly": false, "required": false }, { "name": "custom_attribute_values", "type": "map", "description": "A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair\nis a [CatalogCustomAttributeValue](entity:CatalogCustomAttributeValue) object. The key is the `key` attribute\nvalue defined in the associated [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition)\nobject defined by the application making the request.\n\nIf the `CatalogCustomAttributeDefinition` object is\ndefined by another application, the `CatalogCustomAttributeDefinition`'s key attribute value is prefixed by\nthe defining application ID. For example, if the `CatalogCustomAttributeDefinition` has a `key` attribute of\n`\"cocoa_brand\"` and the defining application ID is `\"abcd1234\"`, the key in the map is `\"abcd1234:cocoa_brand\"`\nif the application making the request is different from the application defining the custom attribute definition.\nOtherwise, the key used in the map is simply `\"cocoa_brand\"`.\n\nApplication-defined custom attributes are set at a global (location-independent) level.\nCustom attribute values are intended to store additional information about a catalog object\nor associations with an entity in another system. Do not use custom attributes\nto store any sensitive information (personally identifiable information, card details, etc.).", "readOnly": false, "required": false }, { "name": "catalog_v1_ids", "type": "array", "description": "The Connect v1 IDs for this object at each location where it is present, where they\ndiffer from the object's Connect V2 ID. The field will only be present for objects that\nhave been created or modified by legacy APIs.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogV1Id" }, { "name": "present_at_all_locations", "type": "boolean", "description": "If `true`, this object is present at all locations (including future locations), except where specified in\nthe `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations),\nexcept where specified in the `present_at_location_ids` field. If not specified, defaults to `true`.", "readOnly": false, "required": false }, { "name": "present_at_location_ids", "type": "array", "description": "A list of locations where the object is present, even if `present_at_all_locations` is `false`.\nThis can include locations that are deactivated.", "readOnly": false, "required": false }, { "name": "absent_at_location_ids", "type": "array", "description": "A list of locations where the object is not present, even if `present_at_all_locations` is `true`.\nThis can include locations that are deactivated.", "readOnly": false, "required": false }, { "name": "item_data", "type": "#/components/schemas/CatalogItem", "description": "Structured data for a `CatalogItem`, set for CatalogObjects of type `ITEM`.", "readOnly": false, "required": false }, { "name": "category_data", "type": "#/components/schemas/CatalogCategory", "description": "Structured data for a `CatalogCategory`, set for CatalogObjects of type `CATEGORY`.", "readOnly": false, "required": false }, { "name": "item_variation_data", "type": "#/components/schemas/CatalogItemVariation", "description": "Structured data for a `CatalogItemVariation`, set for CatalogObjects of type `ITEM_VARIATION`.", "readOnly": false, "required": false }, { "name": "tax_data", "type": "#/components/schemas/CatalogTax", "description": "Structured data for a `CatalogTax`, set for CatalogObjects of type `TAX`.", "readOnly": false, "required": false }, { "name": "discount_data", "type": "#/components/schemas/CatalogDiscount", "description": "Structured data for a `CatalogDiscount`, set for CatalogObjects of type `DISCOUNT`.", "readOnly": false, "required": false }, { "name": "modifier_list_data", "type": "#/components/schemas/CatalogModifierList", "description": "Structured data for a `CatalogModifierList`, set for CatalogObjects of type `MODIFIER_LIST`.", "readOnly": false, "required": false }, { "name": "modifier_data", "type": "#/components/schemas/CatalogModifier", "description": "Structured data for a `CatalogModifier`, set for CatalogObjects of type `MODIFIER`.", "readOnly": false, "required": false }, { "name": "time_period_data", "type": "#/components/schemas/CatalogTimePeriod", "description": "Structured data for a `CatalogTimePeriod`, set for CatalogObjects of type `TIME_PERIOD`.", "readOnly": false, "required": false }, { "name": "product_set_data", "type": "#/components/schemas/CatalogProductSet", "description": "Structured data for a `CatalogProductSet`, set for CatalogObjects of type `PRODUCT_SET`.", "readOnly": false, "required": false }, { "name": "pricing_rule_data", "type": "#/components/schemas/CatalogPricingRule", "description": "Structured data for a `CatalogPricingRule`, set for CatalogObjects of type `PRICING_RULE`.\nA `CatalogPricingRule` object often works with a `CatalogProductSet` object or a `CatalogTimePeriod` object.", "readOnly": false, "required": false }, { "name": "image_data", "type": "#/components/schemas/CatalogImage", "description": "Structured data for a `CatalogImage`, set for CatalogObjects of type `IMAGE`.", "readOnly": false, "required": false }, { "name": "measurement_unit_data", "type": "#/components/schemas/CatalogMeasurementUnit", "description": "Structured data for a `CatalogMeasurementUnit`, set for CatalogObjects of type `MEASUREMENT_UNIT`.", "readOnly": false, "required": false }, { "name": "subscription_plan_data", "type": "#/components/schemas/CatalogSubscriptionPlan", "description": "Structured data for a `CatalogSubscriptionPlan`, set for CatalogObjects of type `SUBSCRIPTION_PLAN`.", "readOnly": false, "required": false }, { "name": "item_option_data", "type": "#/components/schemas/CatalogItemOption", "description": "Structured data for a `CatalogItemOption`, set for CatalogObjects of type `ITEM_OPTION`.", "readOnly": false, "required": false }, { "name": "item_option_value_data", "type": "#/components/schemas/CatalogItemOptionValue", "description": "Structured data for a `CatalogItemOptionValue`, set for CatalogObjects of type `ITEM_OPTION_VAL`.", "readOnly": false, "required": false }, { "name": "custom_attribute_definition_data", "type": "#/components/schemas/CatalogCustomAttributeDefinition", "description": "Structured data for a `CatalogCustomAttributeDefinition`, set for CatalogObjects of type `CUSTOM_ATTRIBUTE_DEFINITION`.", "readOnly": false, "required": false }, { "name": "quick_amounts_settings_data", "type": "#/components/schemas/CatalogQuickAmountsSettings", "description": "Structured data for a `CatalogQuickAmountsSettings`, set for CatalogObjects of type `QUICK_AMOUNTS_SETTINGS`.", "readOnly": false, "required": false }, { "name": "subscription_plan_variation_data", "type": "#/components/schemas/CatalogSubscriptionPlanVariation", "description": "Structured data for a `CatalogSubscriptionPlanVariation`, set for CatalogObjects of type `SUBSCRIPTION_PLAN_VARIATION`.", "readOnly": false, "required": false }, { "name": "availability_period_data", "type": "#/components/schemas/CatalogAvailabilityPeriod", "description": "Structured data for a `CatalogAvailabilityPeriod`, set for CatalogObjects of type `AVAILABILITY_PERIOD`.", "readOnly": false, "required": false } ] }, { "name": "CatalogObjectType", "properties": [] }, { "name": "CatalogV1Id", "properties": [ { "name": "catalog_v1_id", "type": "string", "description": "The ID for an object used in the Square API V1, if the object ID differs from the Square API V2 object ID.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the `Location` this Connect V1 ID is associated with.", "readOnly": false, "required": false } ] }, { "name": "CatalogItem", "properties": [ { "name": "name", "type": "string", "description": "The item's name. This is a searchable attribute for use in applicable query filters, its value must not be empty, and the length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The item's description. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.\n\nDeprecated at 2022-07-20, this field is planned to retire in 6 months. You should migrate to use `description_html` to set the description\nof the [CatalogItem](entity:CatalogItem) instance. The `description` and `description_html` field values are kept in sync. If you try to\nset the both fields, the `description_html` text value overwrites the `description` value. Updates in one field are also reflected in the other,\nexcept for when you use an early version before Square API 2022-07-20 and `description_html` is set to blank, setting the `description` value to null\ndoes not nullify `description_html`.", "readOnly": false, "required": false }, { "name": "abbreviation", "type": "string", "description": "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.\nThis attribute is searchable, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "label_color", "type": "string", "description": "The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code.", "readOnly": false, "required": false }, { "name": "is_taxable", "type": "boolean", "description": "Indicates whether the item is taxable (`true`) or non-taxable (`false`). Default is `true`.", "readOnly": false, "required": false }, { "name": "category_id", "type": "string", "description": "The ID of the item's category, if any. Deprecated since 2023-12-13. Use `CatalogItem.categories`, instead.", "readOnly": false, "required": false }, { "name": "tax_ids", "type": "array", "description": "A set of IDs indicating the taxes enabled for\nthis item. When updating an item, any taxes listed here will be added to the item.\nTaxes may also be added to or deleted from an item using `UpdateItemTaxes`.", "readOnly": false, "required": false }, { "name": "modifier_list_info", "type": "array", "description": "A set of `CatalogItemModifierListInfo` objects\nrepresenting the modifier lists that apply to this item, along with the overrides and min\nand max limits that are specific to this item. Modifier lists\nmay also be added to or deleted from an item using `UpdateItemModifierLists`.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemModifierListInfo" }, { "name": "variations", "type": "array", "description": "A list of [CatalogItemVariation](entity:CatalogItemVariation) objects for this item. An item must have\nat least one variation.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" }, { "name": "product_type", "type": "#/components/schemas/CatalogItemProductType", "description": "The product type of the item. Once set, the `product_type` value cannot be modified.\n\nItems of the `LEGACY_SQUARE_ONLINE_SERVICE` and `LEGACY_SQUARE_ONLINE_MEMBERSHIP` product types can be updated\nbut cannot be created using the API.\n", "readOnly": false, "required": false }, { "name": "skip_modifier_screen", "type": "boolean", "description": "If `false`, the Square Point of Sale app will present the `CatalogItem`'s\ndetails screen immediately, allowing the merchant to choose `CatalogModifier`s\nbefore adding the item to the cart. This is the default behavior.\n\nIf `true`, the Square Point of Sale app will immediately add the item to the cart with the pre-selected\nmodifiers, and merchants can edit modifiers by drilling down onto the item's details.\n\nThird-party clients are encouraged to implement similar behaviors.", "readOnly": false, "required": false }, { "name": "item_options", "type": "array", "description": "List of item options IDs for this item. Used to manage and group item\nvariations in a specified order.\n\nMaximum: 6 item options.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemOptionForItem" }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogItem` instance.\nThese images will be shown to customers in Square Online Store.\nThe first image will show up as the icon for this item in POS.", "readOnly": false, "required": false }, { "name": "sort_name", "type": "string", "description": "A name to sort the item by. If this name is unspecified, namely, the `sort_name` field is absent, the regular `name` field is used for sorting.\nIts value must not be empty.\n\nIt is currently supported for sellers of the Japanese locale only.", "readOnly": false, "required": false }, { "name": "categories", "type": "array", "description": "The list of categories.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObjectCategory" }, { "name": "description_html", "type": "string", "description": "The item's description as expressed in valid HTML elements. The length of this field value, including those of HTML tags,\nis of Unicode points. With application query filters, the text values of the HTML elements and attributes are searchable. Invalid or\nunsupported HTML elements or attributes are ignored.\n\nSupported HTML elements include:\n- `a`: Link. Supports linking to website URLs, email address, and telephone numbers.\n- `b`, `strong`: Bold text\n- `br`: Line break\n- `code`: Computer code\n- `div`: Section\n- `h1-h6`: Headings\n- `i`, `em`: Italics\n- `li`: List element\n- `ol`: Numbered list\n- `p`: Paragraph\n- `ul`: Bullet list\n- `u`: Underline\n\n\nSupported HTML attributes include:\n- `align`: Alignment of the text content\n- `href`: Link destination\n- `rel`: Relationship between link's target and source\n- `target`: Place to open the linked document", "readOnly": false, "required": false }, { "name": "description_plaintext", "type": "string", "description": "A server-generated plaintext version of the `description_html` field, without formatting tags.", "readOnly": true, "required": false }, { "name": "channels", "type": "array", "description": "A list of IDs representing channels, such as a Square Online site, where the item can be made visible or available.\nThis field is read only and cannot be edited.", "readOnly": false, "required": false }, { "name": "is_archived", "type": "boolean", "description": "Indicates whether this item is archived (`true`) or not (`false`).", "readOnly": false, "required": false }, { "name": "ecom_seo_data", "type": "#/components/schemas/CatalogEcomSeoData", "description": "The SEO data for a seller's Square Online store.", "readOnly": false, "required": false }, { "name": "food_and_beverage_details", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetails", "description": "The food and beverage-specific details for the `FOOD_AND_BEV` item.", "readOnly": false, "required": false }, { "name": "reporting_category", "type": "#/components/schemas/CatalogObjectCategory", "description": "The item's reporting category.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemModifierListInfo", "properties": [ { "name": "modifier_list_id", "type": "string", "description": "The ID of the `CatalogModifierList` controlled by this `CatalogModifierListInfo`.", "readOnly": false, "required": true }, { "name": "modifier_overrides", "type": "array", "description": "A set of `CatalogModifierOverride` objects that override whether a given `CatalogModifier` is enabled by default.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogModifierOverride" }, { "name": "min_selected_modifiers", "type": "integer", "description": "If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`", "readOnly": false, "required": false }, { "name": "max_selected_modifiers", "type": "integer", "description": "If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "If `true`, enable this `CatalogModifierList`. The default value is `true`.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The position of this `CatalogItemModifierListInfo` object within the `modifier_list_info` list applied \nto a `CatalogItem` instance.", "readOnly": false, "required": false } ] }, { "name": "CatalogModifierOverride", "properties": [ { "name": "modifier_id", "type": "string", "description": "The ID of the `CatalogModifier` whose default behavior is being overridden.", "readOnly": false, "required": true }, { "name": "on_by_default", "type": "boolean", "description": "If `true`, this `CatalogModifier` should be selected by default for this `CatalogItem`.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemProductType", "properties": [] }, { "name": "CatalogItemOptionForItem", "properties": [ { "name": "item_option_id", "type": "string", "description": "The unique id of the item option, used to form the dimensions of the item option matrix in a specified order.", "readOnly": false, "required": false } ] }, { "name": "CatalogObjectCategory", "properties": [ { "name": "id", "type": "string", "description": "The ID of the object's category.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The order of the object within the context of the category.", "readOnly": false, "required": false } ] }, { "name": "CatalogEcomSeoData", "properties": [ { "name": "page_title", "type": "string", "description": "The SEO title used for the Square Online store.", "readOnly": false, "required": false }, { "name": "page_description", "type": "string", "description": "The SEO description used for the Square Online store.", "readOnly": false, "required": false }, { "name": "permalink", "type": "string", "description": "The SEO permalink used for the Square Online store.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemFoodAndBeverageDetails", "properties": [ { "name": "calorie_count", "type": "integer", "description": "The calorie count (in the unit of kcal) for the `FOOD_AND_BEV` type of items.", "readOnly": false, "required": false }, { "name": "dietary_preferences", "type": "array", "description": "The dietary preferences for the `FOOD_AND_BEV` item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreference" }, { "name": "ingredients", "type": "array", "description": "The ingredients for the `FOOD_AND_BEV` type item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemFoodAndBeverageDetailsIngredient" } ] }, { "name": "CatalogItemFoodAndBeverageDetailsDietaryPreference", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "description": "The dietary preference type. Supported values include `STANDARD` and `CUSTOM` as specified in `FoodAndBeverageDetails.DietaryPreferenceType`.\n", "readOnly": false, "required": false }, { "name": "standard_name", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference", "description": "The name of the dietary preference from a standard pre-defined list. This should be null if it's a custom dietary preference.\n", "readOnly": false, "required": false }, { "name": "custom_name", "type": "string", "description": "The name of a user-defined custom dietary preference. This should be null if it's a standard dietary preference.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "properties": [] }, { "name": "CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference", "properties": [] }, { "name": "CatalogItemFoodAndBeverageDetailsIngredient", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "description": "The dietary preference type of the ingredient. Supported values include `STANDARD` and `CUSTOM` as specified in `FoodAndBeverageDetails.DietaryPreferenceType`.\n", "readOnly": false, "required": false }, { "name": "standard_name", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient", "description": "The name of the ingredient from a standard pre-defined list. This should be null if it's a custom dietary preference.\n", "readOnly": false, "required": false }, { "name": "custom_name", "type": "string", "description": "The name of a custom user-defined ingredient. This should be null if it's a standard dietary preference.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient", "properties": [] }, { "name": "CatalogCategory", "properties": [ { "name": "name", "type": "string", "description": "The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogCategory` instance.\nCurrently these images are not displayed by Square, but are free to be displayed in 3rd party applications.", "readOnly": false, "required": false }, { "name": "category_type", "type": "#/components/schemas/CatalogCategoryType", "description": "The type of the category.\n", "readOnly": false, "required": false }, { "name": "parent_category", "type": "#/components/schemas/CatalogObjectCategory", "description": "The ID of the parent category of this category instance.", "readOnly": false, "required": false }, { "name": "is_top_level", "type": "boolean", "description": "Indicates whether a category is a top level category, which does not have any parent_category.", "readOnly": false, "required": false }, { "name": "channels", "type": "array", "description": "A list of IDs representing channels, such as a Square Online site, where the category can be made visible.", "readOnly": false, "required": false }, { "name": "availability_period_ids", "type": "array", "description": "The IDs of the `CatalogAvailabilityPeriod` objects associated with the category.", "readOnly": false, "required": false }, { "name": "online_visibility", "type": "boolean", "description": "Indicates whether the category is visible (`true`) or hidden (`false`) on all of the seller's Square Online sites.", "readOnly": false, "required": false }, { "name": "root_category", "type": "string", "description": "The top-level category in a category hierarchy.", "readOnly": true, "required": false }, { "name": "ecom_seo_data", "type": "#/components/schemas/CatalogEcomSeoData", "description": "The SEO data for a seller's Square Online store.", "readOnly": false, "required": false }, { "name": "path_to_root", "type": "array", "description": "The path from the category to its root category. The first node of the path is the parent of the category\nand the last is the root category. The path is empty if the category is a root category.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CategoryPathToRootNode" } ] }, { "name": "CatalogCategoryType", "properties": [] }, { "name": "CategoryPathToRootNode", "properties": [ { "name": "category_id", "type": "string", "description": "The category's ID.", "readOnly": false, "required": false }, { "name": "category_name", "type": "string", "description": "The category's name.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemVariation", "properties": [ { "name": "item_id", "type": "string", "description": "The ID of the `CatalogItem` associated with this item variation.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The item variation's name. This is a searchable attribute for use in applicable query filters.\n\nIts value has a maximum length of 255 Unicode code points. However, when the parent [item](entity:CatalogItem)\nuses [item options](entity:CatalogItemOption), this attribute is auto-generated, read-only, and can be\nlonger than 255 Unicode code points.", "readOnly": false, "required": false }, { "name": "sku", "type": "string", "description": "The item variation's SKU, if any. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "upc", "type": "string", "description": "The universal product code (UPC) of the item variation, if any. This is a searchable attribute for use in applicable query filters.\n\nThe value of this attribute should be a number of 12-14 digits long. This restriction is enforced on the Square Seller Dashboard,\nSquare Point of Sale or Retail Point of Sale apps, where this attribute shows in the GTIN field. If a non-compliant UPC value is assigned\nto this attribute using the API, the value is not editable on the Seller Dashboard, Square Point of Sale or Retail Point of Sale apps\nunless it is updated to fit the expected format.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal\nfor each item variation within a parent `CatalogItem` is set according to the item variations's\nposition. On reads, the value is not guaranteed to be sequential or unique.", "readOnly": true, "required": false }, { "name": "pricing_type", "type": "#/components/schemas/CatalogPricingType", "description": "Indicates whether the item variation's price is fixed or determined at the time\nof sale.\n", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The item variation's price, if fixed pricing is used.", "readOnly": false, "required": false }, { "name": "location_overrides", "type": "array", "description": "Per-location price and inventory overrides.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/ItemVariationLocationOverrides" }, { "name": "track_inventory", "type": "boolean", "description": "If `true`, inventory tracking is active for the variation.", "readOnly": false, "required": false }, { "name": "inventory_alert_type", "type": "#/components/schemas/InventoryAlertType", "description": "Indicates whether the item variation displays an alert when its inventory quantity is less than or equal\nto its `inventory_alert_threshold`.\n", "readOnly": false, "required": false }, { "name": "inventory_alert_threshold", "type": "integer", "description": "If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`\nis `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.\n\nThis value is always an integer.", "readOnly": false, "required": false }, { "name": "user_data", "type": "string", "description": "Arbitrary user metadata to associate with the item variation. This attribute value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "service_duration", "type": "integer", "description": "If the `CatalogItem` that owns this item variation is of type\n`APPOINTMENTS_SERVICE`, then this is the duration of the service in milliseconds. For\nexample, a 30 minute appointment would have the value `1800000`, which is equal to\n30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second).", "readOnly": false, "required": false }, { "name": "available_for_booking", "type": "boolean", "description": "If the `CatalogItem` that owns this item variation is of type\n`APPOINTMENTS_SERVICE`, a bool representing whether this service is available for booking.", "readOnly": false, "required": false }, { "name": "item_option_values", "type": "array", "description": "List of item option values associated with this item variation. Listed\nin the same order as the item options of the parent item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemOptionValueForItemVariation" }, { "name": "measurement_unit_id", "type": "string", "description": "ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity\nsold of this item variation. If left unset, the item will be sold in\nwhole quantities.", "readOnly": false, "required": false }, { "name": "sellable", "type": "boolean", "description": "Whether this variation can be sold. The inventory count of a sellable variation indicates\nthe number of units available for sale. When a variation is both stockable and sellable,\nits sellable inventory count can be smaller than or equal to its stockable count.", "readOnly": false, "required": false }, { "name": "stockable", "type": "boolean", "description": "Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE).\nWhen a variation is both stockable and sellable, the inventory count of a stockable variation keeps track of the number of units of this variation in stock\nand is not an indicator of the number of units of the variation that can be sold.", "readOnly": false, "required": false }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogItemVariation` instance.\nThese images will be shown to customers in Square Online Store.", "readOnly": false, "required": false }, { "name": "team_member_ids", "type": "array", "description": "Tokens of employees that can perform the service represented by this variation. Only valid for\nvariations of type `APPOINTMENTS_SERVICE`.", "readOnly": false, "required": false }, { "name": "stockable_conversion", "type": "#/components/schemas/CatalogStockConversion", "description": "The unit conversion rule, as prescribed by the [CatalogStockConversion](entity:CatalogStockConversion) type,\nthat describes how this non-stockable (i.e., sellable/receivable) item variation is converted\nto/from the stockable item variation sharing the same parent item. With the stock conversion,\nyou can accurately track inventory when an item variation is sold in one unit, but stocked in\nanother unit.", "readOnly": false, "required": false } ] }, { "name": "CatalogPricingType", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "ItemVariationLocationOverrides", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the `Location`. This can include locations that are deactivated.", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The price of the `CatalogItemVariation` at the given `Location`, or blank for variable pricing.", "readOnly": false, "required": false }, { "name": "pricing_type", "type": "#/components/schemas/CatalogPricingType", "description": "The pricing type (fixed or variable) for the `CatalogItemVariation` at the given `Location`.\n", "readOnly": false, "required": false }, { "name": "track_inventory", "type": "boolean", "description": "If `true`, inventory tracking is active for the `CatalogItemVariation` at this `Location`.", "readOnly": false, "required": false }, { "name": "inventory_alert_type", "type": "#/components/schemas/InventoryAlertType", "description": "Indicates whether the `CatalogItemVariation` displays an alert when its inventory\nquantity is less than or equal to its `inventory_alert_threshold`.\n", "readOnly": false, "required": false }, { "name": "inventory_alert_threshold", "type": "integer", "description": "If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`\nis `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.\n\nThis value is always an integer.", "readOnly": false, "required": false }, { "name": "sold_out", "type": "boolean", "description": "Indicates whether the overridden item variation is sold out at the specified location.\n\nWhen inventory tracking is enabled on the item variation either globally or at the specified location,\nthe item variation is automatically marked as sold out when its inventory count reaches zero. The seller\ncan manually set the item variation as sold out even when the inventory count is greater than zero.\nAttempts by an application to set this attribute are ignored. Regardless how the sold-out status is set,\napplications should treat its inventory count as zero when this attribute value is `true`.", "readOnly": true, "required": false }, { "name": "sold_out_valid_until", "type": "string", "description": "The seller-assigned timestamp, of the RFC 3339 format, to indicate when this sold-out variation\nbecomes available again at the specified location. Attempts by an application to set this attribute are ignored.\nWhen the current time is later than this attribute value, the affected item variation is no longer sold out.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "InventoryAlertType", "properties": [] }, { "name": "CatalogItemOptionValueForItemVariation", "properties": [ { "name": "item_option_id", "type": "string", "description": "The unique id of an item option.", "readOnly": false, "required": false }, { "name": "item_option_value_id", "type": "string", "description": "The unique id of the selected value for the item option.", "readOnly": false, "required": false } ] }, { "name": "CatalogStockConversion", "properties": [ { "name": "stockable_item_variation_id", "type": "string", "description": "References to the stockable [CatalogItemVariation](entity:CatalogItemVariation)\nfor this stock conversion. Selling, receiving or recounting the non-stockable `CatalogItemVariation`\ndefined with a stock conversion results in adjustments of this stockable `CatalogItemVariation`.\nThis immutable field must reference a stockable `CatalogItemVariation`\nthat shares the parent [CatalogItem](entity:CatalogItem) of the converted `CatalogItemVariation.`", "readOnly": false, "required": true }, { "name": "stockable_quantity", "type": "string", "description": "The quantity of the stockable item variation (as identified by `stockable_item_variation_id`)\nequivalent to the non-stockable item variation quantity (as specified in `nonstockable_quantity`)\nas defined by this stock conversion. It accepts a decimal number in a string format that can take\nup to 10 digits before the decimal point and up to 5 digits after the decimal point.", "readOnly": false, "required": true }, { "name": "nonstockable_quantity", "type": "string", "description": "The converted equivalent quantity of the non-stockable [CatalogItemVariation](entity:CatalogItemVariation)\nin its measurement unit. The `stockable_quantity` value and this `nonstockable_quantity` value together\ndefine the conversion ratio between stockable item variation and the non-stockable item variation.\nIt accepts a decimal number in a string format that can take up to 10 digits before the decimal point\nand up to 5 digits after the decimal point.", "readOnly": false, "required": true } ] }, { "name": "CatalogTax", "properties": [ { "name": "name", "type": "string", "description": "The tax's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/TaxCalculationPhase", "description": "Whether the tax is calculated based on a payment's subtotal or total.\n", "readOnly": false, "required": false }, { "name": "inclusion_type", "type": "#/components/schemas/TaxInclusionType", "description": "Whether the tax is `ADDITIVE` or `INCLUSIVE`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign.\nA value of `7.5` corresponds to 7.5%. For a location-specific tax rate, contact the tax authority of the location or a tax consultant.", "readOnly": false, "required": false }, { "name": "applies_to_custom_amounts", "type": "boolean", "description": "If `true`, the fee applies to custom amounts entered into the Square Point of Sale\napp that are not associated with a particular `CatalogItem`.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "A Boolean flag to indicate whether the tax is displayed as enabled (`true`) in the Square Point of Sale app or not (`false`).", "readOnly": false, "required": false }, { "name": "applies_to_product_set_id", "type": "string", "description": "The ID of a `CatalogProductSet` object. If set, the tax is applicable to all products in the product set.", "readOnly": false, "required": false } ] }, { "name": "TaxCalculationPhase", "properties": [] }, { "name": "TaxInclusionType", "properties": [] }, { "name": "CatalogDiscount", "properties": [ { "name": "name", "type": "string", "description": "The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "discount_type", "type": "#/components/schemas/CatalogDiscountType", "description": "Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the discount as a string representation of a decimal number, using a `.` as the decimal\nseparator and without a `%` sign. A value of `7.5` corresponds to `7.5%`. Specify a percentage of `0` if `discount_type`\nis `VARIABLE_PERCENTAGE`.\n\nDo not use this field for amount-based or variable discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of the discount. Specify an amount of `0` if `discount_type` is `VARIABLE_AMOUNT`.\n\nDo not use this field for percentage-based or variable discounts.", "readOnly": false, "required": false }, { "name": "pin_required", "type": "boolean", "description": "Indicates whether a mobile staff member needs to enter their PIN to apply the\ndiscount to a payment in the Square Point of Sale app.", "readOnly": false, "required": false }, { "name": "label_color", "type": "string", "description": "The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code.", "readOnly": false, "required": false }, { "name": "modify_tax_basis", "type": "#/components/schemas/CatalogDiscountModifyTaxBasis", "description": "Indicates whether this discount should reduce the price used to calculate tax.\n\nMost discounts should use `MODIFY_TAX_BASIS`. However, in some circumstances taxes must\nbe calculated based on an item's price, ignoring a particular discount. For example,\nin many US jurisdictions, a manufacturer coupon or instant rebate reduces the price a\ncustomer pays but does not reduce the sale price used to calculate how much sales tax is\ndue. In this case, the discount representing that manufacturer coupon should have\n`DO_NOT_MODIFY_TAX_BASIS` for this field.\n\nIf you are unsure whether you need to use this field, consult your tax professional.\n", "readOnly": false, "required": false }, { "name": "maximum_amount_money", "type": "#/components/schemas/Money", "description": "For a percentage discount, the maximum absolute value of the discount. For example, if a\n50% discount has a `maximum_amount_money` of $20, a $100 purchase will yield a $20 discount,\nnot a $50 discount.", "readOnly": false, "required": false } ] }, { "name": "CatalogDiscountType", "properties": [] }, { "name": "CatalogDiscountModifyTaxBasis", "properties": [] }, { "name": "CatalogModifierList", "properties": [ { "name": "name", "type": "string", "description": "The name of the `CatalogModifierList` instance. This is a searchable attribute for use in applicable query filters, and its value length is of \nUnicode code points.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The position of this `CatalogModifierList` within a list of `CatalogModifierList` instances.", "readOnly": false, "required": false }, { "name": "selection_type", "type": "#/components/schemas/CatalogModifierListSelectionType", "description": "Indicates whether a single (`SINGLE`) or multiple (`MULTIPLE`) modifiers from the list\ncan be applied to a single `CatalogItem`.\n\nFor text-based modifiers, the `selection_type` attribute is always `SINGLE`. The other value is ignored.\n", "readOnly": false, "required": false }, { "name": "modifiers", "type": "array", "description": "A non-empty list of `CatalogModifier` objects to be included in the `CatalogModifierList`, \nfor non text-based modifiers when the `modifier_type` attribute is `LIST`. Each element of this list \nis a `CatalogObject` instance of the `MODIFIER` type, containing the following attributes:\n```\n{\n\"id\": \"{{catalog_modifier_id}}\",\n\"type\": \"MODIFIER\", \n\"modifier_data\": {{a CatalogModifier instance>}} \n}\n```", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogModifierList` instance.\nCurrently these images are not displayed on Square products, but may be displayed in 3rd-party applications.", "readOnly": false, "required": false }, { "name": "modifier_type", "type": "#/components/schemas/CatalogModifierListModifierType", "description": "The type of the modifier. \n\nWhen this `modifier_type` value is `TEXT`, the `CatalogModifierList` represents a text-based modifier. \nWhen this `modifier_type` value is `LIST`, the `CatalogModifierList` contains a list of `CatalogModifier` objects.\n", "readOnly": false, "required": false }, { "name": "max_length", "type": "integer", "description": "The maximum length, in Unicode points, of the text string of the text-based modifier as represented by \nthis `CatalogModifierList` object with the `modifier_type` set to `TEXT`.", "readOnly": false, "required": false }, { "name": "text_required", "type": "boolean", "description": "Whether the text string must be a non-empty string (`true`) or not (`false`) for a text-based modifier\nas represented by this `CatalogModifierList` object with the `modifier_type` set to `TEXT`.", "readOnly": false, "required": false }, { "name": "internal_name", "type": "string", "description": "A note for internal use by the business. \n\nFor example, for a text-based modifier applied to a T-shirt item, if the buyer-supplied text of \"Hello, Kitty!\" \nis to be printed on the T-shirt, this `internal_name` attribute can be \"Use italic face\" as \nan instruction for the business to follow. \n\nFor non text-based modifiers, this `internal_name` attribute can be \nused to include SKUs, internal codes, or supplemental descriptions for internal use.", "readOnly": false, "required": false } ] }, { "name": "CatalogModifierListSelectionType", "properties": [] }, { "name": "CatalogModifierListModifierType", "properties": [] }, { "name": "CatalogModifier", "properties": [ { "name": "name", "type": "string", "description": "The modifier name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The modifier price.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "Determines where this `CatalogModifier` appears in the `CatalogModifierList`.", "readOnly": false, "required": false }, { "name": "modifier_list_id", "type": "string", "description": "The ID of the `CatalogModifierList` associated with this modifier.", "readOnly": false, "required": false }, { "name": "location_overrides", "type": "array", "description": "Location-specific price overrides.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/ModifierLocationOverrides" }, { "name": "image_id", "type": "string", "description": "The ID of the image associated with this `CatalogModifier` instance.\nCurrently this image is not displayed by Square, but is free to be displayed in 3rd party applications.", "readOnly": false, "required": false } ] }, { "name": "ModifierLocationOverrides", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the `Location` object representing the location. This can include a deactivated location.", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The overridden price at the specified location. If this is unspecified, the modifier price is not overridden.\nThe modifier becomes free of charge at the specified location, when this `price_money` field is set to 0.", "readOnly": false, "required": false }, { "name": "sold_out", "type": "boolean", "description": "Indicates whether the modifier is sold out at the specified location or not. As an example, for cheese (modifier) burger (item), when the modifier is sold out, it is the cheese, but not the burger, that is sold out.\nThe seller can manually set this sold out status. Attempts by an application to set this attribute are ignored.", "readOnly": true, "required": false } ] }, { "name": "CatalogTimePeriod", "properties": [ { "name": "event", "type": "string", "description": "An iCalendar (RFC 5545) [event](https://tools.ietf.org/html/rfc5545#section-3.6.1), which\nspecifies the name, timing, duration and recurrence of this time period.\n\nExample:\n\n```\nDTSTART:20190707T180000\nDURATION:P2H\nRRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR\n```\n\nOnly `SUMMARY`, `DTSTART`, `DURATION` and `RRULE` fields are supported.\n`DTSTART` must be in local (unzoned) time format. Note that while `BEGIN:VEVENT`\nand `END:VEVENT` is not required in the request. The response will always\ninclude them.", "readOnly": false, "required": false } ] }, { "name": "CatalogProductSet", "properties": [ { "name": "name", "type": "string", "description": "User-defined name for the product set. For example, \"Clearance Items\"\nor \"Winter Sale Items\".", "readOnly": false, "required": false }, { "name": "product_ids_any", "type": "array", "description": " Unique IDs for any `CatalogObject` included in this product set. Any\nnumber of these catalog objects can be in an order for a pricing rule to apply.\n\nThis can be used with `product_ids_all` in a parent `CatalogProductSet` to\nmatch groups of products for a bulk discount, such as a discount for an\nentree and side combo.\n\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.\n\nMax: 500 catalog object IDs.", "readOnly": false, "required": false }, { "name": "product_ids_all", "type": "array", "description": "Unique IDs for any `CatalogObject` included in this product set.\nAll objects in this set must be included in an order for a pricing rule to apply.\n\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.\n\nMax: 500 catalog object IDs.", "readOnly": false, "required": false }, { "name": "quantity_exact", "type": "integer", "description": "If set, there must be exactly this many items from `products_any` or `products_all`\nin the cart for the discount to apply.\n\nCannot be combined with either `quantity_min` or `quantity_max`.", "readOnly": false, "required": false }, { "name": "quantity_min", "type": "integer", "description": "If set, there must be at least this many items from `products_any` or `products_all`\nin a cart for the discount to apply. See `quantity_exact`. Defaults to 0 if\n`quantity_exact`, `quantity_min` and `quantity_max` are all unspecified.", "readOnly": false, "required": false }, { "name": "quantity_max", "type": "integer", "description": "If set, the pricing rule will apply to a maximum of this many items from\n`products_any` or `products_all`.", "readOnly": false, "required": false }, { "name": "all_products", "type": "boolean", "description": "If set to `true`, the product set will include every item in the catalog.\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.", "readOnly": false, "required": false } ] }, { "name": "CatalogPricingRule", "properties": [ { "name": "name", "type": "string", "description": "User-defined name for the pricing rule. For example, \"Buy one get one\nfree\" or \"10% off\".", "readOnly": false, "required": false }, { "name": "time_period_ids", "type": "array", "description": "A list of unique IDs for the catalog time periods when\nthis pricing rule is in effect. If left unset, the pricing rule is always\nin effect.", "readOnly": false, "required": false }, { "name": "discount_id", "type": "string", "description": "Unique ID for the `CatalogDiscount` to take off\nthe price of all matched items.", "readOnly": false, "required": false }, { "name": "match_products_id", "type": "string", "description": "Unique ID for the `CatalogProductSet` that will be matched by this rule. A match rule\nmatches within the entire cart, and can match multiple times. This field will always be set.", "readOnly": false, "required": false }, { "name": "apply_products_id", "type": "string", "description": "__Deprecated__: Please use the `exclude_products_id` field to apply\nan exclude set instead. Exclude sets allow better control over quantity\nranges and offer more flexibility for which matched items receive a discount.\n\n`CatalogProductSet` to apply the pricing to.\nAn apply rule matches within the subset of the cart that fits the match rules (the match set).\nAn apply rule can only match once in the match set.\nIf not supplied, the pricing will be applied to all products in the match set.\nOther products retain their base price, or a price generated by other rules.", "readOnly": false, "required": false }, { "name": "exclude_products_id", "type": "string", "description": "`CatalogProductSet` to exclude from the pricing rule.\nAn exclude rule matches within the subset of the cart that fits the match rules (the match set).\nAn exclude rule can only match once in the match set.\nIf not supplied, the pricing will be applied to all products in the match set.\nOther products retain their base price, or a price generated by other rules.", "readOnly": false, "required": false }, { "name": "valid_from_date", "type": "string", "description": "Represents the date the Pricing Rule is valid from. Represented in RFC 3339 full-date format (YYYY-MM-DD).", "readOnly": false, "required": false }, { "name": "valid_from_local_time", "type": "string", "description": "Represents the local time the pricing rule should be valid from. Represented in RFC 3339 partial-time format\n(HH:MM:SS). Partial seconds will be truncated.", "readOnly": false, "required": false }, { "name": "valid_until_date", "type": "string", "description": "Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD).", "readOnly": false, "required": false }, { "name": "valid_until_local_time", "type": "string", "description": "Represents the local time the pricing rule should be valid until. Represented in RFC 3339 partial-time format\n(HH:MM:SS). Partial seconds will be truncated.", "readOnly": false, "required": false }, { "name": "exclude_strategy", "type": "#/components/schemas/ExcludeStrategy", "description": "If an `exclude_products_id` was given, controls which subset of matched\nproducts is excluded from any discounts.\n\nDefault value: `LEAST_EXPENSIVE`\n", "readOnly": false, "required": false }, { "name": "minimum_order_subtotal_money", "type": "#/components/schemas/Money", "description": "The minimum order subtotal (before discounts or taxes are applied)\nthat must be met before this rule may be applied.", "readOnly": false, "required": false }, { "name": "customer_group_ids_any", "type": "array", "description": "A list of IDs of customer groups, the members of which are eligible for discounts specified in this pricing rule.\nNotice that a group ID is generated by the Customers API.\nIf this field is not set, the specified discount applies to matched products sold to anyone whether the buyer\nhas a customer profile created or not. If this `customer_group_ids_any` field is set, the specified discount\napplies only to matched products sold to customers belonging to the specified customer groups.", "readOnly": false, "required": false } ] }, { "name": "ExcludeStrategy", "properties": [] }, { "name": "CatalogImage", "properties": [ { "name": "name", "type": "string", "description": "The internal name to identify this image in calls to the Square API.\nThis is a searchable attribute for use in applicable query filters\nusing the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).\nIt is not unique and should not be shown in a buyer facing context.", "readOnly": false, "required": false }, { "name": "url", "type": "string", "description": "The URL of this image, generated by Square after an image is uploaded\nusing the [CreateCatalogImage](api-endpoint:Catalog-CreateCatalogImage) endpoint.\nTo modify the image, use the UpdateCatalogImage endpoint. Do not change the URL field.", "readOnly": false, "required": false }, { "name": "caption", "type": "string", "description": "A caption that describes what is shown in the image. Displayed in the\nSquare Online Store. This is a searchable attribute for use in applicable query filters\nusing the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).", "readOnly": false, "required": false }, { "name": "photo_studio_order_id", "type": "string", "description": "The immutable order ID for this image object created by the Photo Studio service in Square Online Store.", "readOnly": false, "required": false } ] }, { "name": "CatalogMeasurementUnit", "properties": [ { "name": "measurement_unit", "type": "#/components/schemas/MeasurementUnit", "description": "Indicates the unit used to measure the quantity of a catalog item variation.", "readOnly": false, "required": false }, { "name": "precision", "type": "integer", "description": "An integer between 0 and 5 that represents the maximum number of\npositions allowed after the decimal in quantities measured with this unit.\nFor example:\n\n- if the precision is 0, the quantity can be 1, 2, 3, etc.\n- if the precision is 1, the quantity can be 0.1, 0.2, etc.\n- if the precision is 2, the quantity can be 0.01, 0.12, etc.\n\nDefault: 3", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnit", "properties": [ { "name": "custom_unit", "type": "#/components/schemas/MeasurementUnitCustom", "description": "A custom unit of measurement defined by the seller using the Point of Sale\napp or ad-hoc as an order line item.", "readOnly": false, "required": false }, { "name": "area_unit", "type": "#/components/schemas/MeasurementUnitArea", "description": "Represents a standard area unit.\n", "readOnly": false, "required": false }, { "name": "length_unit", "type": "#/components/schemas/MeasurementUnitLength", "description": "Represents a standard length unit.\n", "readOnly": false, "required": false }, { "name": "volume_unit", "type": "#/components/schemas/MeasurementUnitVolume", "description": "Represents a standard volume unit.\n", "readOnly": false, "required": false }, { "name": "weight_unit", "type": "#/components/schemas/MeasurementUnitWeight", "description": "Represents a standard unit of weight or mass.\n", "readOnly": false, "required": false }, { "name": "generic_unit", "type": "#/components/schemas/MeasurementUnitGeneric", "description": "Reserved for API integrations that lack the ability to specify a real measurement unit\n", "readOnly": false, "required": false }, { "name": "time_unit", "type": "#/components/schemas/MeasurementUnitTime", "description": "Represents a standard unit of time.\n", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/MeasurementUnitUnitType", "description": "Represents the type of the measurement unit.\n", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnitCustom", "properties": [ { "name": "name", "type": "string", "description": "The name of the custom unit, for example \"bushel\".", "readOnly": false, "required": true }, { "name": "abbreviation", "type": "string", "description": "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears\nin the cart for the Point of Sale app, and in reports.", "readOnly": false, "required": true } ] }, { "name": "MeasurementUnitArea", "properties": [] }, { "name": "MeasurementUnitLength", "properties": [] }, { "name": "MeasurementUnitVolume", "properties": [] }, { "name": "MeasurementUnitWeight", "properties": [] }, { "name": "MeasurementUnitGeneric", "properties": [] }, { "name": "MeasurementUnitTime", "properties": [] }, { "name": "MeasurementUnitUnitType", "properties": [] }, { "name": "CatalogSubscriptionPlan", "properties": [ { "name": "name", "type": "string", "description": "The name of the plan.", "readOnly": false, "required": true }, { "name": "phases", "type": "array", "description": "A list of SubscriptionPhase containing the [SubscriptionPhase](entity:SubscriptionPhase) for this plan.\nThis field it required. Not including this field will throw a REQUIRED_FIELD_MISSING error", "readOnly": false, "required": false, "arrayType": "#/components/schemas/SubscriptionPhase" }, { "name": "subscription_plan_variations", "type": "array", "description": "The list of subscription plan variations available for this product", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" }, { "name": "eligible_item_ids", "type": "array", "description": "The list of IDs of `CatalogItems` that are eligible for subscription by this SubscriptionPlan's variations.", "readOnly": false, "required": false }, { "name": "eligible_category_ids", "type": "array", "description": "The list of IDs of `CatalogCategory` that are eligible for subscription by this SubscriptionPlan's variations.", "readOnly": false, "required": false }, { "name": "all_items", "type": "boolean", "description": "If true, all items in the merchant's catalog are subscribable by this SubscriptionPlan.", "readOnly": false, "required": false } ] }, { "name": "SubscriptionPhase", "properties": [ { "name": "uid", "type": "string", "description": "The Square-assigned ID of the subscription phase. This field cannot be changed after a `SubscriptionPhase` is created.", "readOnly": false, "required": false }, { "name": "cadence", "type": "#/components/schemas/SubscriptionCadence", "description": "The billing cadence of the phase. For example, weekly or monthly. This field cannot be changed after a `SubscriptionPhase` is created.\n", "readOnly": false, "required": true }, { "name": "periods", "type": "integer", "description": "The number of `cadence`s the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after a `SubscriptionPhase` is created.", "readOnly": false, "required": false }, { "name": "recurring_price_money", "type": "#/components/schemas/Money", "description": "The amount to bill for each `cadence`. Failure to specify this field results in a `MISSING_REQUIRED_PARAMETER` error at runtime.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a `SubscriptionPhase` is created.", "readOnly": false, "required": false }, { "name": "pricing", "type": "#/components/schemas/SubscriptionPricing", "description": "The subscription pricing.", "readOnly": false, "required": false } ] }, { "name": "SubscriptionCadence", "properties": [] }, { "name": "SubscriptionPricing", "properties": [ { "name": "type", "type": "#/components/schemas/SubscriptionPricingType", "description": "RELATIVE or STATIC\n", "readOnly": false, "required": false }, { "name": "discount_ids", "type": "array", "description": "The ids of the discount catalog objects", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The price of the subscription, if STATIC", "readOnly": false, "required": false } ] }, { "name": "SubscriptionPricingType", "properties": [] }, { "name": "CatalogItemOption", "properties": [ { "name": "name", "type": "string", "description": "The item option's display name for the seller. Must be unique across\nall item options. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "display_name", "type": "string", "description": "The item option's display name for the customer. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The item option's human-readable description. Displayed in the Square\nPoint of Sale app for the seller and in the Online Store or on receipts for\nthe buyer. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "show_colors", "type": "boolean", "description": "If true, display colors for entries in `values` when present.", "readOnly": false, "required": false }, { "name": "values", "type": "array", "description": "A list of CatalogObjects containing the\n`CatalogItemOptionValue`s for this item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" } ] }, { "name": "CatalogItemOptionValue", "properties": [ { "name": "item_option_id", "type": "string", "description": "Unique ID of the associated item option.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "Name of this item option value. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "A human-readable description for the option value. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "color", "type": "string", "description": "The HTML-supported hex color for the item option (e.g., \"#ff8d4e85\").\nOnly displayed if `show_colors` is enabled on the parent `ItemOption`. When\nleft unset, `color` defaults to white (\"#ffffff\") when `show_colors` is\nenabled on the parent `ItemOption`.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "Determines where this option value appears in a list of option values.", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinition", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogCustomAttributeDefinitionType", "description": "The type of this custom attribute. Cannot be modified after creation.\nRequired.\n", "readOnly": false, "required": true }, { "name": "name", "type": "string", "description": " The name of this definition for API and seller-facing UI purposes.\nThe name must be unique within the (merchant, application) pair. Required.\nMay not be empty and may not exceed 255 characters. Can be modified after creation.", "readOnly": false, "required": true }, { "name": "description", "type": "string", "description": "Seller-oriented description of the meaning of this Custom Attribute,\nany constraints that the seller should observe, etc. May be displayed as a tooltip in Square UIs.", "readOnly": false, "required": false }, { "name": "source_application", "type": "#/components/schemas/SourceApplication", "description": "__Read only.__ Contains information about the application that\ncreated this custom attribute definition.", "readOnly": false, "required": false }, { "name": "allowed_object_types", "type": "array", "description": "The set of `CatalogObject` types that this custom atttribute may be applied to.\nCurrently, only `ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, and `CATEGORY` are allowed. At least one type must be included.\n", "readOnly": false, "required": true, "arrayType": "#/components/schemas/CatalogObjectType" }, { "name": "seller_visibility", "type": "#/components/schemas/CatalogCustomAttributeDefinitionSellerVisibility", "description": "The visibility of a custom attribute in seller-facing UIs (including Square Point\nof Sale applications and Square Dashboard). May be modified.\n", "readOnly": false, "required": false }, { "name": "app_visibility", "type": "#/components/schemas/CatalogCustomAttributeDefinitionAppVisibility", "description": "The visibility of a custom attribute to applications other than the application\nthat created the attribute.\n", "readOnly": false, "required": false }, { "name": "string_config", "type": "#/components/schemas/CatalogCustomAttributeDefinitionStringConfig", "description": "Optionally, populated when `type` = `STRING`, unset otherwise.", "readOnly": false, "required": false }, { "name": "number_config", "type": "#/components/schemas/CatalogCustomAttributeDefinitionNumberConfig", "description": "Optionally, populated when `type` = `NUMBER`, unset otherwise.", "readOnly": false, "required": false }, { "name": "selection_config", "type": "#/components/schemas/CatalogCustomAttributeDefinitionSelectionConfig", "description": "Populated when `type` is set to `SELECTION`, unset otherwise.", "readOnly": false, "required": false }, { "name": "custom_attribute_usage_count", "type": "integer", "description": "The number of custom attributes that reference this\ncustom attribute definition. Set by the server in response to a ListCatalog\nrequest with `include_counts` set to `true`. If the actual count is greater\nthan 100, `custom_attribute_usage_count` will be set to `100`.", "readOnly": true, "required": false }, { "name": "key", "type": "string", "description": "The name of the desired custom attribute key that can be used to access\nthe custom attribute value on catalog objects. Cannot be modified after the\ncustom attribute definition has been created.\nMust be between 1 and 60 characters, and may only contain the characters `[a-zA-Z0-9_-]`.", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinitionType", "properties": [] }, { "name": "SourceApplication", "properties": [ { "name": "product", "type": "#/components/schemas/Product", "description": "__Read only__ The [product](entity:Product) type of the application.\n", "readOnly": false, "required": false }, { "name": "application_id", "type": "string", "description": "__Read only__ The Square-assigned ID of the application. This field is used only if the\n[product](entity:Product) type is `EXTERNAL_API`.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "__Read only__ The display name of the application\n(for example, `\"Custom Application\"` or `\"Square POS 4.74 for Android\"`).", "readOnly": false, "required": false } ] }, { "name": "Product", "properties": [] }, { "name": "CatalogCustomAttributeDefinitionSellerVisibility", "properties": [] }, { "name": "CatalogCustomAttributeDefinitionAppVisibility", "properties": [] }, { "name": "CatalogCustomAttributeDefinitionStringConfig", "properties": [ { "name": "enforce_uniqueness", "type": "boolean", "description": "If true, each Custom Attribute instance associated with this Custom Attribute\nDefinition must have a unique value within the seller's catalog. For\nexample, this may be used for a value like a SKU that should not be\nduplicated within a seller's catalog. May not be modified after the\ndefinition has been created.", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinitionNumberConfig", "properties": [ { "name": "precision", "type": "integer", "description": "An integer between 0 and 5 that represents the maximum number of\npositions allowed after the decimal in number custom attribute values\nFor example:\n\n- if the precision is 0, the quantity can be 1, 2, 3, etc.\n- if the precision is 1, the quantity can be 0.1, 0.2, etc.\n- if the precision is 2, the quantity can be 0.01, 0.12, etc.\n\nDefault: 5", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinitionSelectionConfig", "properties": [ { "name": "max_allowed_selections", "type": "integer", "description": "The maximum number of selections that can be set. The maximum value for this\nattribute is 100. The default value is 1. The value can be modified, but changing the value will not\naffect existing custom attribute values on objects. Clients need to\nhandle custom attributes with more selected values than allowed by this limit.", "readOnly": false, "required": false }, { "name": "allowed_selections", "type": "array", "description": "The set of valid `CatalogCustomAttributeSelections`. Up to a maximum of 100\nselections can be defined. Can be modified.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection" } ] }, { "name": "CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection", "properties": [ { "name": "uid", "type": "string", "description": "Unique ID set by Square.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "Selection name, unique within `allowed_selections`.", "readOnly": false, "required": true } ] }, { "name": "CatalogQuickAmountsSettings", "properties": [ { "name": "option", "type": "#/components/schemas/CatalogQuickAmountsSettingsOption", "description": "Represents the option seller currently uses on Quick Amounts.\n", "readOnly": false, "required": true }, { "name": "eligible_for_auto_amounts", "type": "boolean", "description": "Represents location's eligibility for auto amounts\nThe boolean should be consistent with whether there are AUTO amounts in the `amounts`.", "readOnly": false, "required": false }, { "name": "amounts", "type": "array", "description": "Represents a set of Quick Amounts at this location.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogQuickAmount" } ] }, { "name": "CatalogQuickAmountsSettingsOption", "properties": [] }, { "name": "CatalogQuickAmount", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogQuickAmountType", "description": "Represents the type of the Quick Amount.\n", "readOnly": false, "required": true }, { "name": "amount", "type": "#/components/schemas/Money", "description": "Represents the actual amount of the Quick Amount with Money type.", "readOnly": false, "required": true }, { "name": "score", "type": "integer", "description": "Describes the ranking of the Quick Amount provided by machine learning model, in the range [0, 100].\nMANUAL type amount will always have score = 100.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The order in which this Quick Amount should be displayed.", "readOnly": false, "required": false } ] }, { "name": "CatalogQuickAmountType", "properties": [] }, { "name": "CatalogSubscriptionPlanVariation", "properties": [ { "name": "name", "type": "string", "description": "The name of the plan variation.", "readOnly": false, "required": true }, { "name": "phases", "type": "array", "description": "A list containing each [SubscriptionPhase](entity:SubscriptionPhase) for this plan variation.", "readOnly": false, "required": true, "arrayType": "#/components/schemas/SubscriptionPhase" }, { "name": "subscription_plan_id", "type": "string", "description": "The id of the subscription plan, if there is one.", "readOnly": false, "required": false }, { "name": "monthly_billing_anchor_date", "type": "integer", "description": "The day of the month the billing period starts.", "readOnly": false, "required": false }, { "name": "can_prorate", "type": "boolean", "description": "Whether bills for this plan variation can be split for proration.", "readOnly": false, "required": false }, { "name": "successor_plan_variation_id", "type": "string", "description": "The ID of a \"successor\" plan variation to this one. If the field is set, and this object is disabled at all\nlocations, it indicates that this variation is deprecated and the object identified by the successor ID be used in\nits stead.", "readOnly": false, "required": false } ] }, { "name": "CatalogAvailabilityPeriod", "properties": [ { "name": "start_local_time", "type": "string", "description": "The start time of an availability period, specified in local time using partial-time\nRFC 3339 format. For example, `8:30:00` for a period starting at 8:30 in the morning.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC.", "readOnly": false, "required": false }, { "name": "end_local_time", "type": "string", "description": "The end time of an availability period, specified in local time using partial-time\nRFC 3339 format. For example, `21:00:00` for a period ending at 9:00 in the evening.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC.", "readOnly": false, "required": false }, { "name": "day_of_week", "type": "#/components/schemas/DayOfWeek", "description": "The day of the week for this availability period.\n", "readOnly": false, "required": false } ] }, { "name": "DayOfWeek", "properties": [] } ], "CreateCatalogImageRequest": [ { "name": "CreateCatalogImageRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this CreateCatalogImage request.\nKeys can be any valid string but must be unique for every CreateCatalogImage request.\n\nSee [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information.", "readOnly": false, "required": true }, { "name": "object_id", "type": "string", "description": "Unique ID of the `CatalogObject` to attach this `CatalogImage` object to. Leave this\nfield empty to create unattached images, for example if you are building an integration\nwhere an image can be attached to catalog items at a later time.", "readOnly": false, "required": false }, { "name": "image", "type": "#/components/schemas/CatalogObject", "description": "The new `CatalogObject` of the `IMAGE` type, namely, a `CatalogImage` object, to encapsulate the specified image file.", "readOnly": false, "required": true }, { "name": "is_primary", "type": "boolean", "description": "If this is set to `true`, the image created will be the primary, or first image of the object referenced by `object_id`.\nIf the `CatalogObject` already has a primary `CatalogImage`, setting this field to `true` will replace the primary image.\nIf this is set to `false` and you use the Square API version 2021-12-15 or later, the image id will be appended to the list of `image_ids` on the object.\n\nWith Square API version 2021-12-15 or later, the default value is `false`. Otherwise, the effective default value is `true`.", "readOnly": false, "required": false }, { "name": "image_file", "type": "string", "description": "Path to the image file to upload", "readOnly": false, "required": true, "isFile": true } ] }, { "name": "CatalogObject", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogObjectType", "description": "The type of this object. Each object type has expected\nproperties expressed in a structured format within its corresponding `*_data` field below.\n", "readOnly": false, "required": true }, { "name": "id", "type": "string", "description": "An identifier to reference this object in the catalog. When a new `CatalogObject`\nis inserted, the client should set the id to a temporary identifier starting with\na \"`#`\" character. Other objects being inserted or updated within the same request\nmay use this identifier to refer to the new object.\n\nWhen the server receives the new object, it will supply a unique identifier that\nreplaces the temporary identifier for all future references.", "readOnly": false, "required": true }, { "name": "updated_at", "type": "string", "description": "Last modification [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) in RFC 3339 format, e.g., `\"2016-08-15T23:59:33.123Z\"`\nwould indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "The version of the object. When updating an object, the version supplied\nmust match the version in the database, otherwise the write will be rejected as conflicting.", "readOnly": false, "required": false }, { "name": "is_deleted", "type": "boolean", "description": "If `true`, the object has been deleted from the database. Must be `false` for new objects\nbeing inserted. When deleted, the `updated_at` field will equal the deletion time.", "readOnly": false, "required": false }, { "name": "custom_attribute_values", "type": "map", "description": "A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair\nis a [CatalogCustomAttributeValue](entity:CatalogCustomAttributeValue) object. The key is the `key` attribute\nvalue defined in the associated [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition)\nobject defined by the application making the request.\n\nIf the `CatalogCustomAttributeDefinition` object is\ndefined by another application, the `CatalogCustomAttributeDefinition`'s key attribute value is prefixed by\nthe defining application ID. For example, if the `CatalogCustomAttributeDefinition` has a `key` attribute of\n`\"cocoa_brand\"` and the defining application ID is `\"abcd1234\"`, the key in the map is `\"abcd1234:cocoa_brand\"`\nif the application making the request is different from the application defining the custom attribute definition.\nOtherwise, the key used in the map is simply `\"cocoa_brand\"`.\n\nApplication-defined custom attributes are set at a global (location-independent) level.\nCustom attribute values are intended to store additional information about a catalog object\nor associations with an entity in another system. Do not use custom attributes\nto store any sensitive information (personally identifiable information, card details, etc.).", "readOnly": false, "required": false }, { "name": "catalog_v1_ids", "type": "array", "description": "The Connect v1 IDs for this object at each location where it is present, where they\ndiffer from the object's Connect V2 ID. The field will only be present for objects that\nhave been created or modified by legacy APIs.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogV1Id" }, { "name": "present_at_all_locations", "type": "boolean", "description": "If `true`, this object is present at all locations (including future locations), except where specified in\nthe `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations),\nexcept where specified in the `present_at_location_ids` field. If not specified, defaults to `true`.", "readOnly": false, "required": false }, { "name": "present_at_location_ids", "type": "array", "description": "A list of locations where the object is present, even if `present_at_all_locations` is `false`.\nThis can include locations that are deactivated.", "readOnly": false, "required": false }, { "name": "absent_at_location_ids", "type": "array", "description": "A list of locations where the object is not present, even if `present_at_all_locations` is `true`.\nThis can include locations that are deactivated.", "readOnly": false, "required": false }, { "name": "item_data", "type": "#/components/schemas/CatalogItem", "description": "Structured data for a `CatalogItem`, set for CatalogObjects of type `ITEM`.", "readOnly": false, "required": false }, { "name": "category_data", "type": "#/components/schemas/CatalogCategory", "description": "Structured data for a `CatalogCategory`, set for CatalogObjects of type `CATEGORY`.", "readOnly": false, "required": false }, { "name": "item_variation_data", "type": "#/components/schemas/CatalogItemVariation", "description": "Structured data for a `CatalogItemVariation`, set for CatalogObjects of type `ITEM_VARIATION`.", "readOnly": false, "required": false }, { "name": "tax_data", "type": "#/components/schemas/CatalogTax", "description": "Structured data for a `CatalogTax`, set for CatalogObjects of type `TAX`.", "readOnly": false, "required": false }, { "name": "discount_data", "type": "#/components/schemas/CatalogDiscount", "description": "Structured data for a `CatalogDiscount`, set for CatalogObjects of type `DISCOUNT`.", "readOnly": false, "required": false }, { "name": "modifier_list_data", "type": "#/components/schemas/CatalogModifierList", "description": "Structured data for a `CatalogModifierList`, set for CatalogObjects of type `MODIFIER_LIST`.", "readOnly": false, "required": false }, { "name": "modifier_data", "type": "#/components/schemas/CatalogModifier", "description": "Structured data for a `CatalogModifier`, set for CatalogObjects of type `MODIFIER`.", "readOnly": false, "required": false }, { "name": "time_period_data", "type": "#/components/schemas/CatalogTimePeriod", "description": "Structured data for a `CatalogTimePeriod`, set for CatalogObjects of type `TIME_PERIOD`.", "readOnly": false, "required": false }, { "name": "product_set_data", "type": "#/components/schemas/CatalogProductSet", "description": "Structured data for a `CatalogProductSet`, set for CatalogObjects of type `PRODUCT_SET`.", "readOnly": false, "required": false }, { "name": "pricing_rule_data", "type": "#/components/schemas/CatalogPricingRule", "description": "Structured data for a `CatalogPricingRule`, set for CatalogObjects of type `PRICING_RULE`.\nA `CatalogPricingRule` object often works with a `CatalogProductSet` object or a `CatalogTimePeriod` object.", "readOnly": false, "required": false }, { "name": "image_data", "type": "#/components/schemas/CatalogImage", "description": "Structured data for a `CatalogImage`, set for CatalogObjects of type `IMAGE`.", "readOnly": false, "required": false }, { "name": "measurement_unit_data", "type": "#/components/schemas/CatalogMeasurementUnit", "description": "Structured data for a `CatalogMeasurementUnit`, set for CatalogObjects of type `MEASUREMENT_UNIT`.", "readOnly": false, "required": false }, { "name": "subscription_plan_data", "type": "#/components/schemas/CatalogSubscriptionPlan", "description": "Structured data for a `CatalogSubscriptionPlan`, set for CatalogObjects of type `SUBSCRIPTION_PLAN`.", "readOnly": false, "required": false }, { "name": "item_option_data", "type": "#/components/schemas/CatalogItemOption", "description": "Structured data for a `CatalogItemOption`, set for CatalogObjects of type `ITEM_OPTION`.", "readOnly": false, "required": false }, { "name": "item_option_value_data", "type": "#/components/schemas/CatalogItemOptionValue", "description": "Structured data for a `CatalogItemOptionValue`, set for CatalogObjects of type `ITEM_OPTION_VAL`.", "readOnly": false, "required": false }, { "name": "custom_attribute_definition_data", "type": "#/components/schemas/CatalogCustomAttributeDefinition", "description": "Structured data for a `CatalogCustomAttributeDefinition`, set for CatalogObjects of type `CUSTOM_ATTRIBUTE_DEFINITION`.", "readOnly": false, "required": false }, { "name": "quick_amounts_settings_data", "type": "#/components/schemas/CatalogQuickAmountsSettings", "description": "Structured data for a `CatalogQuickAmountsSettings`, set for CatalogObjects of type `QUICK_AMOUNTS_SETTINGS`.", "readOnly": false, "required": false }, { "name": "subscription_plan_variation_data", "type": "#/components/schemas/CatalogSubscriptionPlanVariation", "description": "Structured data for a `CatalogSubscriptionPlanVariation`, set for CatalogObjects of type `SUBSCRIPTION_PLAN_VARIATION`.", "readOnly": false, "required": false }, { "name": "availability_period_data", "type": "#/components/schemas/CatalogAvailabilityPeriod", "description": "Structured data for a `CatalogAvailabilityPeriod`, set for CatalogObjects of type `AVAILABILITY_PERIOD`.", "readOnly": false, "required": false } ] }, { "name": "CatalogObjectType", "properties": [] }, { "name": "CatalogV1Id", "properties": [ { "name": "catalog_v1_id", "type": "string", "description": "The ID for an object used in the Square API V1, if the object ID differs from the Square API V2 object ID.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the `Location` this Connect V1 ID is associated with.", "readOnly": false, "required": false } ] }, { "name": "CatalogItem", "properties": [ { "name": "name", "type": "string", "description": "The item's name. This is a searchable attribute for use in applicable query filters, its value must not be empty, and the length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The item's description. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.\n\nDeprecated at 2022-07-20, this field is planned to retire in 6 months. You should migrate to use `description_html` to set the description\nof the [CatalogItem](entity:CatalogItem) instance. The `description` and `description_html` field values are kept in sync. If you try to\nset the both fields, the `description_html` text value overwrites the `description` value. Updates in one field are also reflected in the other,\nexcept for when you use an early version before Square API 2022-07-20 and `description_html` is set to blank, setting the `description` value to null\ndoes not nullify `description_html`.", "readOnly": false, "required": false }, { "name": "abbreviation", "type": "string", "description": "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.\nThis attribute is searchable, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "label_color", "type": "string", "description": "The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code.", "readOnly": false, "required": false }, { "name": "is_taxable", "type": "boolean", "description": "Indicates whether the item is taxable (`true`) or non-taxable (`false`). Default is `true`.", "readOnly": false, "required": false }, { "name": "category_id", "type": "string", "description": "The ID of the item's category, if any. Deprecated since 2023-12-13. Use `CatalogItem.categories`, instead.", "readOnly": false, "required": false }, { "name": "tax_ids", "type": "array", "description": "A set of IDs indicating the taxes enabled for\nthis item. When updating an item, any taxes listed here will be added to the item.\nTaxes may also be added to or deleted from an item using `UpdateItemTaxes`.", "readOnly": false, "required": false }, { "name": "modifier_list_info", "type": "array", "description": "A set of `CatalogItemModifierListInfo` objects\nrepresenting the modifier lists that apply to this item, along with the overrides and min\nand max limits that are specific to this item. Modifier lists\nmay also be added to or deleted from an item using `UpdateItemModifierLists`.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemModifierListInfo" }, { "name": "variations", "type": "array", "description": "A list of [CatalogItemVariation](entity:CatalogItemVariation) objects for this item. An item must have\nat least one variation.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" }, { "name": "product_type", "type": "#/components/schemas/CatalogItemProductType", "description": "The product type of the item. Once set, the `product_type` value cannot be modified.\n\nItems of the `LEGACY_SQUARE_ONLINE_SERVICE` and `LEGACY_SQUARE_ONLINE_MEMBERSHIP` product types can be updated\nbut cannot be created using the API.\n", "readOnly": false, "required": false }, { "name": "skip_modifier_screen", "type": "boolean", "description": "If `false`, the Square Point of Sale app will present the `CatalogItem`'s\ndetails screen immediately, allowing the merchant to choose `CatalogModifier`s\nbefore adding the item to the cart. This is the default behavior.\n\nIf `true`, the Square Point of Sale app will immediately add the item to the cart with the pre-selected\nmodifiers, and merchants can edit modifiers by drilling down onto the item's details.\n\nThird-party clients are encouraged to implement similar behaviors.", "readOnly": false, "required": false }, { "name": "item_options", "type": "array", "description": "List of item options IDs for this item. Used to manage and group item\nvariations in a specified order.\n\nMaximum: 6 item options.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemOptionForItem" }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogItem` instance.\nThese images will be shown to customers in Square Online Store.\nThe first image will show up as the icon for this item in POS.", "readOnly": false, "required": false }, { "name": "sort_name", "type": "string", "description": "A name to sort the item by. If this name is unspecified, namely, the `sort_name` field is absent, the regular `name` field is used for sorting.\nIts value must not be empty.\n\nIt is currently supported for sellers of the Japanese locale only.", "readOnly": false, "required": false }, { "name": "categories", "type": "array", "description": "The list of categories.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObjectCategory" }, { "name": "description_html", "type": "string", "description": "The item's description as expressed in valid HTML elements. The length of this field value, including those of HTML tags,\nis of Unicode points. With application query filters, the text values of the HTML elements and attributes are searchable. Invalid or\nunsupported HTML elements or attributes are ignored.\n\nSupported HTML elements include:\n- `a`: Link. Supports linking to website URLs, email address, and telephone numbers.\n- `b`, `strong`: Bold text\n- `br`: Line break\n- `code`: Computer code\n- `div`: Section\n- `h1-h6`: Headings\n- `i`, `em`: Italics\n- `li`: List element\n- `ol`: Numbered list\n- `p`: Paragraph\n- `ul`: Bullet list\n- `u`: Underline\n\n\nSupported HTML attributes include:\n- `align`: Alignment of the text content\n- `href`: Link destination\n- `rel`: Relationship between link's target and source\n- `target`: Place to open the linked document", "readOnly": false, "required": false }, { "name": "description_plaintext", "type": "string", "description": "A server-generated plaintext version of the `description_html` field, without formatting tags.", "readOnly": true, "required": false }, { "name": "channels", "type": "array", "description": "A list of IDs representing channels, such as a Square Online site, where the item can be made visible or available.\nThis field is read only and cannot be edited.", "readOnly": false, "required": false }, { "name": "is_archived", "type": "boolean", "description": "Indicates whether this item is archived (`true`) or not (`false`).", "readOnly": false, "required": false }, { "name": "ecom_seo_data", "type": "#/components/schemas/CatalogEcomSeoData", "description": "The SEO data for a seller's Square Online store.", "readOnly": false, "required": false }, { "name": "food_and_beverage_details", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetails", "description": "The food and beverage-specific details for the `FOOD_AND_BEV` item.", "readOnly": false, "required": false }, { "name": "reporting_category", "type": "#/components/schemas/CatalogObjectCategory", "description": "The item's reporting category.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemModifierListInfo", "properties": [ { "name": "modifier_list_id", "type": "string", "description": "The ID of the `CatalogModifierList` controlled by this `CatalogModifierListInfo`.", "readOnly": false, "required": true }, { "name": "modifier_overrides", "type": "array", "description": "A set of `CatalogModifierOverride` objects that override whether a given `CatalogModifier` is enabled by default.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogModifierOverride" }, { "name": "min_selected_modifiers", "type": "integer", "description": "If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`", "readOnly": false, "required": false }, { "name": "max_selected_modifiers", "type": "integer", "description": "If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "If `true`, enable this `CatalogModifierList`. The default value is `true`.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The position of this `CatalogItemModifierListInfo` object within the `modifier_list_info` list applied \nto a `CatalogItem` instance.", "readOnly": false, "required": false } ] }, { "name": "CatalogModifierOverride", "properties": [ { "name": "modifier_id", "type": "string", "description": "The ID of the `CatalogModifier` whose default behavior is being overridden.", "readOnly": false, "required": true }, { "name": "on_by_default", "type": "boolean", "description": "If `true`, this `CatalogModifier` should be selected by default for this `CatalogItem`.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemProductType", "properties": [] }, { "name": "CatalogItemOptionForItem", "properties": [ { "name": "item_option_id", "type": "string", "description": "The unique id of the item option, used to form the dimensions of the item option matrix in a specified order.", "readOnly": false, "required": false } ] }, { "name": "CatalogObjectCategory", "properties": [ { "name": "id", "type": "string", "description": "The ID of the object's category.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The order of the object within the context of the category.", "readOnly": false, "required": false } ] }, { "name": "CatalogEcomSeoData", "properties": [ { "name": "page_title", "type": "string", "description": "The SEO title used for the Square Online store.", "readOnly": false, "required": false }, { "name": "page_description", "type": "string", "description": "The SEO description used for the Square Online store.", "readOnly": false, "required": false }, { "name": "permalink", "type": "string", "description": "The SEO permalink used for the Square Online store.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemFoodAndBeverageDetails", "properties": [ { "name": "calorie_count", "type": "integer", "description": "The calorie count (in the unit of kcal) for the `FOOD_AND_BEV` type of items.", "readOnly": false, "required": false }, { "name": "dietary_preferences", "type": "array", "description": "The dietary preferences for the `FOOD_AND_BEV` item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreference" }, { "name": "ingredients", "type": "array", "description": "The ingredients for the `FOOD_AND_BEV` type item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemFoodAndBeverageDetailsIngredient" } ] }, { "name": "CatalogItemFoodAndBeverageDetailsDietaryPreference", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "description": "The dietary preference type. Supported values include `STANDARD` and `CUSTOM` as specified in `FoodAndBeverageDetails.DietaryPreferenceType`.\n", "readOnly": false, "required": false }, { "name": "standard_name", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference", "description": "The name of the dietary preference from a standard pre-defined list. This should be null if it's a custom dietary preference.\n", "readOnly": false, "required": false }, { "name": "custom_name", "type": "string", "description": "The name of a user-defined custom dietary preference. This should be null if it's a standard dietary preference.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "properties": [] }, { "name": "CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference", "properties": [] }, { "name": "CatalogItemFoodAndBeverageDetailsIngredient", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "description": "The dietary preference type of the ingredient. Supported values include `STANDARD` and `CUSTOM` as specified in `FoodAndBeverageDetails.DietaryPreferenceType`.\n", "readOnly": false, "required": false }, { "name": "standard_name", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient", "description": "The name of the ingredient from a standard pre-defined list. This should be null if it's a custom dietary preference.\n", "readOnly": false, "required": false }, { "name": "custom_name", "type": "string", "description": "The name of a custom user-defined ingredient. This should be null if it's a standard dietary preference.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient", "properties": [] }, { "name": "CatalogCategory", "properties": [ { "name": "name", "type": "string", "description": "The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogCategory` instance.\nCurrently these images are not displayed by Square, but are free to be displayed in 3rd party applications.", "readOnly": false, "required": false }, { "name": "category_type", "type": "#/components/schemas/CatalogCategoryType", "description": "The type of the category.\n", "readOnly": false, "required": false }, { "name": "parent_category", "type": "#/components/schemas/CatalogObjectCategory", "description": "The ID of the parent category of this category instance.", "readOnly": false, "required": false }, { "name": "is_top_level", "type": "boolean", "description": "Indicates whether a category is a top level category, which does not have any parent_category.", "readOnly": false, "required": false }, { "name": "channels", "type": "array", "description": "A list of IDs representing channels, such as a Square Online site, where the category can be made visible.", "readOnly": false, "required": false }, { "name": "availability_period_ids", "type": "array", "description": "The IDs of the `CatalogAvailabilityPeriod` objects associated with the category.", "readOnly": false, "required": false }, { "name": "online_visibility", "type": "boolean", "description": "Indicates whether the category is visible (`true`) or hidden (`false`) on all of the seller's Square Online sites.", "readOnly": false, "required": false }, { "name": "root_category", "type": "string", "description": "The top-level category in a category hierarchy.", "readOnly": true, "required": false }, { "name": "ecom_seo_data", "type": "#/components/schemas/CatalogEcomSeoData", "description": "The SEO data for a seller's Square Online store.", "readOnly": false, "required": false }, { "name": "path_to_root", "type": "array", "description": "The path from the category to its root category. The first node of the path is the parent of the category\nand the last is the root category. The path is empty if the category is a root category.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CategoryPathToRootNode" } ] }, { "name": "CatalogCategoryType", "properties": [] }, { "name": "CategoryPathToRootNode", "properties": [ { "name": "category_id", "type": "string", "description": "The category's ID.", "readOnly": false, "required": false }, { "name": "category_name", "type": "string", "description": "The category's name.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemVariation", "properties": [ { "name": "item_id", "type": "string", "description": "The ID of the `CatalogItem` associated with this item variation.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The item variation's name. This is a searchable attribute for use in applicable query filters.\n\nIts value has a maximum length of 255 Unicode code points. However, when the parent [item](entity:CatalogItem)\nuses [item options](entity:CatalogItemOption), this attribute is auto-generated, read-only, and can be\nlonger than 255 Unicode code points.", "readOnly": false, "required": false }, { "name": "sku", "type": "string", "description": "The item variation's SKU, if any. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "upc", "type": "string", "description": "The universal product code (UPC) of the item variation, if any. This is a searchable attribute for use in applicable query filters.\n\nThe value of this attribute should be a number of 12-14 digits long. This restriction is enforced on the Square Seller Dashboard,\nSquare Point of Sale or Retail Point of Sale apps, where this attribute shows in the GTIN field. If a non-compliant UPC value is assigned\nto this attribute using the API, the value is not editable on the Seller Dashboard, Square Point of Sale or Retail Point of Sale apps\nunless it is updated to fit the expected format.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal\nfor each item variation within a parent `CatalogItem` is set according to the item variations's\nposition. On reads, the value is not guaranteed to be sequential or unique.", "readOnly": true, "required": false }, { "name": "pricing_type", "type": "#/components/schemas/CatalogPricingType", "description": "Indicates whether the item variation's price is fixed or determined at the time\nof sale.\n", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The item variation's price, if fixed pricing is used.", "readOnly": false, "required": false }, { "name": "location_overrides", "type": "array", "description": "Per-location price and inventory overrides.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/ItemVariationLocationOverrides" }, { "name": "track_inventory", "type": "boolean", "description": "If `true`, inventory tracking is active for the variation.", "readOnly": false, "required": false }, { "name": "inventory_alert_type", "type": "#/components/schemas/InventoryAlertType", "description": "Indicates whether the item variation displays an alert when its inventory quantity is less than or equal\nto its `inventory_alert_threshold`.\n", "readOnly": false, "required": false }, { "name": "inventory_alert_threshold", "type": "integer", "description": "If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`\nis `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.\n\nThis value is always an integer.", "readOnly": false, "required": false }, { "name": "user_data", "type": "string", "description": "Arbitrary user metadata to associate with the item variation. This attribute value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "service_duration", "type": "integer", "description": "If the `CatalogItem` that owns this item variation is of type\n`APPOINTMENTS_SERVICE`, then this is the duration of the service in milliseconds. For\nexample, a 30 minute appointment would have the value `1800000`, which is equal to\n30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second).", "readOnly": false, "required": false }, { "name": "available_for_booking", "type": "boolean", "description": "If the `CatalogItem` that owns this item variation is of type\n`APPOINTMENTS_SERVICE`, a bool representing whether this service is available for booking.", "readOnly": false, "required": false }, { "name": "item_option_values", "type": "array", "description": "List of item option values associated with this item variation. Listed\nin the same order as the item options of the parent item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemOptionValueForItemVariation" }, { "name": "measurement_unit_id", "type": "string", "description": "ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity\nsold of this item variation. If left unset, the item will be sold in\nwhole quantities.", "readOnly": false, "required": false }, { "name": "sellable", "type": "boolean", "description": "Whether this variation can be sold. The inventory count of a sellable variation indicates\nthe number of units available for sale. When a variation is both stockable and sellable,\nits sellable inventory count can be smaller than or equal to its stockable count.", "readOnly": false, "required": false }, { "name": "stockable", "type": "boolean", "description": "Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE).\nWhen a variation is both stockable and sellable, the inventory count of a stockable variation keeps track of the number of units of this variation in stock\nand is not an indicator of the number of units of the variation that can be sold.", "readOnly": false, "required": false }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogItemVariation` instance.\nThese images will be shown to customers in Square Online Store.", "readOnly": false, "required": false }, { "name": "team_member_ids", "type": "array", "description": "Tokens of employees that can perform the service represented by this variation. Only valid for\nvariations of type `APPOINTMENTS_SERVICE`.", "readOnly": false, "required": false }, { "name": "stockable_conversion", "type": "#/components/schemas/CatalogStockConversion", "description": "The unit conversion rule, as prescribed by the [CatalogStockConversion](entity:CatalogStockConversion) type,\nthat describes how this non-stockable (i.e., sellable/receivable) item variation is converted\nto/from the stockable item variation sharing the same parent item. With the stock conversion,\nyou can accurately track inventory when an item variation is sold in one unit, but stocked in\nanother unit.", "readOnly": false, "required": false } ] }, { "name": "CatalogPricingType", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "ItemVariationLocationOverrides", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the `Location`. This can include locations that are deactivated.", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The price of the `CatalogItemVariation` at the given `Location`, or blank for variable pricing.", "readOnly": false, "required": false }, { "name": "pricing_type", "type": "#/components/schemas/CatalogPricingType", "description": "The pricing type (fixed or variable) for the `CatalogItemVariation` at the given `Location`.\n", "readOnly": false, "required": false }, { "name": "track_inventory", "type": "boolean", "description": "If `true`, inventory tracking is active for the `CatalogItemVariation` at this `Location`.", "readOnly": false, "required": false }, { "name": "inventory_alert_type", "type": "#/components/schemas/InventoryAlertType", "description": "Indicates whether the `CatalogItemVariation` displays an alert when its inventory\nquantity is less than or equal to its `inventory_alert_threshold`.\n", "readOnly": false, "required": false }, { "name": "inventory_alert_threshold", "type": "integer", "description": "If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`\nis `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.\n\nThis value is always an integer.", "readOnly": false, "required": false }, { "name": "sold_out", "type": "boolean", "description": "Indicates whether the overridden item variation is sold out at the specified location.\n\nWhen inventory tracking is enabled on the item variation either globally or at the specified location,\nthe item variation is automatically marked as sold out when its inventory count reaches zero. The seller\ncan manually set the item variation as sold out even when the inventory count is greater than zero.\nAttempts by an application to set this attribute are ignored. Regardless how the sold-out status is set,\napplications should treat its inventory count as zero when this attribute value is `true`.", "readOnly": true, "required": false }, { "name": "sold_out_valid_until", "type": "string", "description": "The seller-assigned timestamp, of the RFC 3339 format, to indicate when this sold-out variation\nbecomes available again at the specified location. Attempts by an application to set this attribute are ignored.\nWhen the current time is later than this attribute value, the affected item variation is no longer sold out.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "InventoryAlertType", "properties": [] }, { "name": "CatalogItemOptionValueForItemVariation", "properties": [ { "name": "item_option_id", "type": "string", "description": "The unique id of an item option.", "readOnly": false, "required": false }, { "name": "item_option_value_id", "type": "string", "description": "The unique id of the selected value for the item option.", "readOnly": false, "required": false } ] }, { "name": "CatalogStockConversion", "properties": [ { "name": "stockable_item_variation_id", "type": "string", "description": "References to the stockable [CatalogItemVariation](entity:CatalogItemVariation)\nfor this stock conversion. Selling, receiving or recounting the non-stockable `CatalogItemVariation`\ndefined with a stock conversion results in adjustments of this stockable `CatalogItemVariation`.\nThis immutable field must reference a stockable `CatalogItemVariation`\nthat shares the parent [CatalogItem](entity:CatalogItem) of the converted `CatalogItemVariation.`", "readOnly": false, "required": true }, { "name": "stockable_quantity", "type": "string", "description": "The quantity of the stockable item variation (as identified by `stockable_item_variation_id`)\nequivalent to the non-stockable item variation quantity (as specified in `nonstockable_quantity`)\nas defined by this stock conversion. It accepts a decimal number in a string format that can take\nup to 10 digits before the decimal point and up to 5 digits after the decimal point.", "readOnly": false, "required": true }, { "name": "nonstockable_quantity", "type": "string", "description": "The converted equivalent quantity of the non-stockable [CatalogItemVariation](entity:CatalogItemVariation)\nin its measurement unit. The `stockable_quantity` value and this `nonstockable_quantity` value together\ndefine the conversion ratio between stockable item variation and the non-stockable item variation.\nIt accepts a decimal number in a string format that can take up to 10 digits before the decimal point\nand up to 5 digits after the decimal point.", "readOnly": false, "required": true } ] }, { "name": "CatalogTax", "properties": [ { "name": "name", "type": "string", "description": "The tax's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/TaxCalculationPhase", "description": "Whether the tax is calculated based on a payment's subtotal or total.\n", "readOnly": false, "required": false }, { "name": "inclusion_type", "type": "#/components/schemas/TaxInclusionType", "description": "Whether the tax is `ADDITIVE` or `INCLUSIVE`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign.\nA value of `7.5` corresponds to 7.5%. For a location-specific tax rate, contact the tax authority of the location or a tax consultant.", "readOnly": false, "required": false }, { "name": "applies_to_custom_amounts", "type": "boolean", "description": "If `true`, the fee applies to custom amounts entered into the Square Point of Sale\napp that are not associated with a particular `CatalogItem`.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "A Boolean flag to indicate whether the tax is displayed as enabled (`true`) in the Square Point of Sale app or not (`false`).", "readOnly": false, "required": false }, { "name": "applies_to_product_set_id", "type": "string", "description": "The ID of a `CatalogProductSet` object. If set, the tax is applicable to all products in the product set.", "readOnly": false, "required": false } ] }, { "name": "TaxCalculationPhase", "properties": [] }, { "name": "TaxInclusionType", "properties": [] }, { "name": "CatalogDiscount", "properties": [ { "name": "name", "type": "string", "description": "The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "discount_type", "type": "#/components/schemas/CatalogDiscountType", "description": "Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the discount as a string representation of a decimal number, using a `.` as the decimal\nseparator and without a `%` sign. A value of `7.5` corresponds to `7.5%`. Specify a percentage of `0` if `discount_type`\nis `VARIABLE_PERCENTAGE`.\n\nDo not use this field for amount-based or variable discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of the discount. Specify an amount of `0` if `discount_type` is `VARIABLE_AMOUNT`.\n\nDo not use this field for percentage-based or variable discounts.", "readOnly": false, "required": false }, { "name": "pin_required", "type": "boolean", "description": "Indicates whether a mobile staff member needs to enter their PIN to apply the\ndiscount to a payment in the Square Point of Sale app.", "readOnly": false, "required": false }, { "name": "label_color", "type": "string", "description": "The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code.", "readOnly": false, "required": false }, { "name": "modify_tax_basis", "type": "#/components/schemas/CatalogDiscountModifyTaxBasis", "description": "Indicates whether this discount should reduce the price used to calculate tax.\n\nMost discounts should use `MODIFY_TAX_BASIS`. However, in some circumstances taxes must\nbe calculated based on an item's price, ignoring a particular discount. For example,\nin many US jurisdictions, a manufacturer coupon or instant rebate reduces the price a\ncustomer pays but does not reduce the sale price used to calculate how much sales tax is\ndue. In this case, the discount representing that manufacturer coupon should have\n`DO_NOT_MODIFY_TAX_BASIS` for this field.\n\nIf you are unsure whether you need to use this field, consult your tax professional.\n", "readOnly": false, "required": false }, { "name": "maximum_amount_money", "type": "#/components/schemas/Money", "description": "For a percentage discount, the maximum absolute value of the discount. For example, if a\n50% discount has a `maximum_amount_money` of $20, a $100 purchase will yield a $20 discount,\nnot a $50 discount.", "readOnly": false, "required": false } ] }, { "name": "CatalogDiscountType", "properties": [] }, { "name": "CatalogDiscountModifyTaxBasis", "properties": [] }, { "name": "CatalogModifierList", "properties": [ { "name": "name", "type": "string", "description": "The name of the `CatalogModifierList` instance. This is a searchable attribute for use in applicable query filters, and its value length is of \nUnicode code points.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The position of this `CatalogModifierList` within a list of `CatalogModifierList` instances.", "readOnly": false, "required": false }, { "name": "selection_type", "type": "#/components/schemas/CatalogModifierListSelectionType", "description": "Indicates whether a single (`SINGLE`) or multiple (`MULTIPLE`) modifiers from the list\ncan be applied to a single `CatalogItem`.\n\nFor text-based modifiers, the `selection_type` attribute is always `SINGLE`. The other value is ignored.\n", "readOnly": false, "required": false }, { "name": "modifiers", "type": "array", "description": "A non-empty list of `CatalogModifier` objects to be included in the `CatalogModifierList`, \nfor non text-based modifiers when the `modifier_type` attribute is `LIST`. Each element of this list \nis a `CatalogObject` instance of the `MODIFIER` type, containing the following attributes:\n```\n{\n\"id\": \"{{catalog_modifier_id}}\",\n\"type\": \"MODIFIER\", \n\"modifier_data\": {{a CatalogModifier instance>}} \n}\n```", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogModifierList` instance.\nCurrently these images are not displayed on Square products, but may be displayed in 3rd-party applications.", "readOnly": false, "required": false }, { "name": "modifier_type", "type": "#/components/schemas/CatalogModifierListModifierType", "description": "The type of the modifier. \n\nWhen this `modifier_type` value is `TEXT`, the `CatalogModifierList` represents a text-based modifier. \nWhen this `modifier_type` value is `LIST`, the `CatalogModifierList` contains a list of `CatalogModifier` objects.\n", "readOnly": false, "required": false }, { "name": "max_length", "type": "integer", "description": "The maximum length, in Unicode points, of the text string of the text-based modifier as represented by \nthis `CatalogModifierList` object with the `modifier_type` set to `TEXT`.", "readOnly": false, "required": false }, { "name": "text_required", "type": "boolean", "description": "Whether the text string must be a non-empty string (`true`) or not (`false`) for a text-based modifier\nas represented by this `CatalogModifierList` object with the `modifier_type` set to `TEXT`.", "readOnly": false, "required": false }, { "name": "internal_name", "type": "string", "description": "A note for internal use by the business. \n\nFor example, for a text-based modifier applied to a T-shirt item, if the buyer-supplied text of \"Hello, Kitty!\" \nis to be printed on the T-shirt, this `internal_name` attribute can be \"Use italic face\" as \nan instruction for the business to follow. \n\nFor non text-based modifiers, this `internal_name` attribute can be \nused to include SKUs, internal codes, or supplemental descriptions for internal use.", "readOnly": false, "required": false } ] }, { "name": "CatalogModifierListSelectionType", "properties": [] }, { "name": "CatalogModifierListModifierType", "properties": [] }, { "name": "CatalogModifier", "properties": [ { "name": "name", "type": "string", "description": "The modifier name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The modifier price.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "Determines where this `CatalogModifier` appears in the `CatalogModifierList`.", "readOnly": false, "required": false }, { "name": "modifier_list_id", "type": "string", "description": "The ID of the `CatalogModifierList` associated with this modifier.", "readOnly": false, "required": false }, { "name": "location_overrides", "type": "array", "description": "Location-specific price overrides.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/ModifierLocationOverrides" }, { "name": "image_id", "type": "string", "description": "The ID of the image associated with this `CatalogModifier` instance.\nCurrently this image is not displayed by Square, but is free to be displayed in 3rd party applications.", "readOnly": false, "required": false } ] }, { "name": "ModifierLocationOverrides", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the `Location` object representing the location. This can include a deactivated location.", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The overridden price at the specified location. If this is unspecified, the modifier price is not overridden.\nThe modifier becomes free of charge at the specified location, when this `price_money` field is set to 0.", "readOnly": false, "required": false }, { "name": "sold_out", "type": "boolean", "description": "Indicates whether the modifier is sold out at the specified location or not. As an example, for cheese (modifier) burger (item), when the modifier is sold out, it is the cheese, but not the burger, that is sold out.\nThe seller can manually set this sold out status. Attempts by an application to set this attribute are ignored.", "readOnly": true, "required": false } ] }, { "name": "CatalogTimePeriod", "properties": [ { "name": "event", "type": "string", "description": "An iCalendar (RFC 5545) [event](https://tools.ietf.org/html/rfc5545#section-3.6.1), which\nspecifies the name, timing, duration and recurrence of this time period.\n\nExample:\n\n```\nDTSTART:20190707T180000\nDURATION:P2H\nRRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR\n```\n\nOnly `SUMMARY`, `DTSTART`, `DURATION` and `RRULE` fields are supported.\n`DTSTART` must be in local (unzoned) time format. Note that while `BEGIN:VEVENT`\nand `END:VEVENT` is not required in the request. The response will always\ninclude them.", "readOnly": false, "required": false } ] }, { "name": "CatalogProductSet", "properties": [ { "name": "name", "type": "string", "description": "User-defined name for the product set. For example, \"Clearance Items\"\nor \"Winter Sale Items\".", "readOnly": false, "required": false }, { "name": "product_ids_any", "type": "array", "description": " Unique IDs for any `CatalogObject` included in this product set. Any\nnumber of these catalog objects can be in an order for a pricing rule to apply.\n\nThis can be used with `product_ids_all` in a parent `CatalogProductSet` to\nmatch groups of products for a bulk discount, such as a discount for an\nentree and side combo.\n\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.\n\nMax: 500 catalog object IDs.", "readOnly": false, "required": false }, { "name": "product_ids_all", "type": "array", "description": "Unique IDs for any `CatalogObject` included in this product set.\nAll objects in this set must be included in an order for a pricing rule to apply.\n\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.\n\nMax: 500 catalog object IDs.", "readOnly": false, "required": false }, { "name": "quantity_exact", "type": "integer", "description": "If set, there must be exactly this many items from `products_any` or `products_all`\nin the cart for the discount to apply.\n\nCannot be combined with either `quantity_min` or `quantity_max`.", "readOnly": false, "required": false }, { "name": "quantity_min", "type": "integer", "description": "If set, there must be at least this many items from `products_any` or `products_all`\nin a cart for the discount to apply. See `quantity_exact`. Defaults to 0 if\n`quantity_exact`, `quantity_min` and `quantity_max` are all unspecified.", "readOnly": false, "required": false }, { "name": "quantity_max", "type": "integer", "description": "If set, the pricing rule will apply to a maximum of this many items from\n`products_any` or `products_all`.", "readOnly": false, "required": false }, { "name": "all_products", "type": "boolean", "description": "If set to `true`, the product set will include every item in the catalog.\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.", "readOnly": false, "required": false } ] }, { "name": "CatalogPricingRule", "properties": [ { "name": "name", "type": "string", "description": "User-defined name for the pricing rule. For example, \"Buy one get one\nfree\" or \"10% off\".", "readOnly": false, "required": false }, { "name": "time_period_ids", "type": "array", "description": "A list of unique IDs for the catalog time periods when\nthis pricing rule is in effect. If left unset, the pricing rule is always\nin effect.", "readOnly": false, "required": false }, { "name": "discount_id", "type": "string", "description": "Unique ID for the `CatalogDiscount` to take off\nthe price of all matched items.", "readOnly": false, "required": false }, { "name": "match_products_id", "type": "string", "description": "Unique ID for the `CatalogProductSet` that will be matched by this rule. A match rule\nmatches within the entire cart, and can match multiple times. This field will always be set.", "readOnly": false, "required": false }, { "name": "apply_products_id", "type": "string", "description": "__Deprecated__: Please use the `exclude_products_id` field to apply\nan exclude set instead. Exclude sets allow better control over quantity\nranges and offer more flexibility for which matched items receive a discount.\n\n`CatalogProductSet` to apply the pricing to.\nAn apply rule matches within the subset of the cart that fits the match rules (the match set).\nAn apply rule can only match once in the match set.\nIf not supplied, the pricing will be applied to all products in the match set.\nOther products retain their base price, or a price generated by other rules.", "readOnly": false, "required": false }, { "name": "exclude_products_id", "type": "string", "description": "`CatalogProductSet` to exclude from the pricing rule.\nAn exclude rule matches within the subset of the cart that fits the match rules (the match set).\nAn exclude rule can only match once in the match set.\nIf not supplied, the pricing will be applied to all products in the match set.\nOther products retain their base price, or a price generated by other rules.", "readOnly": false, "required": false }, { "name": "valid_from_date", "type": "string", "description": "Represents the date the Pricing Rule is valid from. Represented in RFC 3339 full-date format (YYYY-MM-DD).", "readOnly": false, "required": false }, { "name": "valid_from_local_time", "type": "string", "description": "Represents the local time the pricing rule should be valid from. Represented in RFC 3339 partial-time format\n(HH:MM:SS). Partial seconds will be truncated.", "readOnly": false, "required": false }, { "name": "valid_until_date", "type": "string", "description": "Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD).", "readOnly": false, "required": false }, { "name": "valid_until_local_time", "type": "string", "description": "Represents the local time the pricing rule should be valid until. Represented in RFC 3339 partial-time format\n(HH:MM:SS). Partial seconds will be truncated.", "readOnly": false, "required": false }, { "name": "exclude_strategy", "type": "#/components/schemas/ExcludeStrategy", "description": "If an `exclude_products_id` was given, controls which subset of matched\nproducts is excluded from any discounts.\n\nDefault value: `LEAST_EXPENSIVE`\n", "readOnly": false, "required": false }, { "name": "minimum_order_subtotal_money", "type": "#/components/schemas/Money", "description": "The minimum order subtotal (before discounts or taxes are applied)\nthat must be met before this rule may be applied.", "readOnly": false, "required": false }, { "name": "customer_group_ids_any", "type": "array", "description": "A list of IDs of customer groups, the members of which are eligible for discounts specified in this pricing rule.\nNotice that a group ID is generated by the Customers API.\nIf this field is not set, the specified discount applies to matched products sold to anyone whether the buyer\nhas a customer profile created or not. If this `customer_group_ids_any` field is set, the specified discount\napplies only to matched products sold to customers belonging to the specified customer groups.", "readOnly": false, "required": false } ] }, { "name": "ExcludeStrategy", "properties": [] }, { "name": "CatalogImage", "properties": [ { "name": "name", "type": "string", "description": "The internal name to identify this image in calls to the Square API.\nThis is a searchable attribute for use in applicable query filters\nusing the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).\nIt is not unique and should not be shown in a buyer facing context.", "readOnly": false, "required": false }, { "name": "url", "type": "string", "description": "The URL of this image, generated by Square after an image is uploaded\nusing the [CreateCatalogImage](api-endpoint:Catalog-CreateCatalogImage) endpoint.\nTo modify the image, use the UpdateCatalogImage endpoint. Do not change the URL field.", "readOnly": false, "required": false }, { "name": "caption", "type": "string", "description": "A caption that describes what is shown in the image. Displayed in the\nSquare Online Store. This is a searchable attribute for use in applicable query filters\nusing the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).", "readOnly": false, "required": false }, { "name": "photo_studio_order_id", "type": "string", "description": "The immutable order ID for this image object created by the Photo Studio service in Square Online Store.", "readOnly": false, "required": false } ] }, { "name": "CatalogMeasurementUnit", "properties": [ { "name": "measurement_unit", "type": "#/components/schemas/MeasurementUnit", "description": "Indicates the unit used to measure the quantity of a catalog item variation.", "readOnly": false, "required": false }, { "name": "precision", "type": "integer", "description": "An integer between 0 and 5 that represents the maximum number of\npositions allowed after the decimal in quantities measured with this unit.\nFor example:\n\n- if the precision is 0, the quantity can be 1, 2, 3, etc.\n- if the precision is 1, the quantity can be 0.1, 0.2, etc.\n- if the precision is 2, the quantity can be 0.01, 0.12, etc.\n\nDefault: 3", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnit", "properties": [ { "name": "custom_unit", "type": "#/components/schemas/MeasurementUnitCustom", "description": "A custom unit of measurement defined by the seller using the Point of Sale\napp or ad-hoc as an order line item.", "readOnly": false, "required": false }, { "name": "area_unit", "type": "#/components/schemas/MeasurementUnitArea", "description": "Represents a standard area unit.\n", "readOnly": false, "required": false }, { "name": "length_unit", "type": "#/components/schemas/MeasurementUnitLength", "description": "Represents a standard length unit.\n", "readOnly": false, "required": false }, { "name": "volume_unit", "type": "#/components/schemas/MeasurementUnitVolume", "description": "Represents a standard volume unit.\n", "readOnly": false, "required": false }, { "name": "weight_unit", "type": "#/components/schemas/MeasurementUnitWeight", "description": "Represents a standard unit of weight or mass.\n", "readOnly": false, "required": false }, { "name": "generic_unit", "type": "#/components/schemas/MeasurementUnitGeneric", "description": "Reserved for API integrations that lack the ability to specify a real measurement unit\n", "readOnly": false, "required": false }, { "name": "time_unit", "type": "#/components/schemas/MeasurementUnitTime", "description": "Represents a standard unit of time.\n", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/MeasurementUnitUnitType", "description": "Represents the type of the measurement unit.\n", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnitCustom", "properties": [ { "name": "name", "type": "string", "description": "The name of the custom unit, for example \"bushel\".", "readOnly": false, "required": true }, { "name": "abbreviation", "type": "string", "description": "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears\nin the cart for the Point of Sale app, and in reports.", "readOnly": false, "required": true } ] }, { "name": "MeasurementUnitArea", "properties": [] }, { "name": "MeasurementUnitLength", "properties": [] }, { "name": "MeasurementUnitVolume", "properties": [] }, { "name": "MeasurementUnitWeight", "properties": [] }, { "name": "MeasurementUnitGeneric", "properties": [] }, { "name": "MeasurementUnitTime", "properties": [] }, { "name": "MeasurementUnitUnitType", "properties": [] }, { "name": "CatalogSubscriptionPlan", "properties": [ { "name": "name", "type": "string", "description": "The name of the plan.", "readOnly": false, "required": true }, { "name": "phases", "type": "array", "description": "A list of SubscriptionPhase containing the [SubscriptionPhase](entity:SubscriptionPhase) for this plan.\nThis field it required. Not including this field will throw a REQUIRED_FIELD_MISSING error", "readOnly": false, "required": false, "arrayType": "#/components/schemas/SubscriptionPhase" }, { "name": "subscription_plan_variations", "type": "array", "description": "The list of subscription plan variations available for this product", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" }, { "name": "eligible_item_ids", "type": "array", "description": "The list of IDs of `CatalogItems` that are eligible for subscription by this SubscriptionPlan's variations.", "readOnly": false, "required": false }, { "name": "eligible_category_ids", "type": "array", "description": "The list of IDs of `CatalogCategory` that are eligible for subscription by this SubscriptionPlan's variations.", "readOnly": false, "required": false }, { "name": "all_items", "type": "boolean", "description": "If true, all items in the merchant's catalog are subscribable by this SubscriptionPlan.", "readOnly": false, "required": false } ] }, { "name": "SubscriptionPhase", "properties": [ { "name": "uid", "type": "string", "description": "The Square-assigned ID of the subscription phase. This field cannot be changed after a `SubscriptionPhase` is created.", "readOnly": false, "required": false }, { "name": "cadence", "type": "#/components/schemas/SubscriptionCadence", "description": "The billing cadence of the phase. For example, weekly or monthly. This field cannot be changed after a `SubscriptionPhase` is created.\n", "readOnly": false, "required": true }, { "name": "periods", "type": "integer", "description": "The number of `cadence`s the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after a `SubscriptionPhase` is created.", "readOnly": false, "required": false }, { "name": "recurring_price_money", "type": "#/components/schemas/Money", "description": "The amount to bill for each `cadence`. Failure to specify this field results in a `MISSING_REQUIRED_PARAMETER` error at runtime.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a `SubscriptionPhase` is created.", "readOnly": false, "required": false }, { "name": "pricing", "type": "#/components/schemas/SubscriptionPricing", "description": "The subscription pricing.", "readOnly": false, "required": false } ] }, { "name": "SubscriptionCadence", "properties": [] }, { "name": "SubscriptionPricing", "properties": [ { "name": "type", "type": "#/components/schemas/SubscriptionPricingType", "description": "RELATIVE or STATIC\n", "readOnly": false, "required": false }, { "name": "discount_ids", "type": "array", "description": "The ids of the discount catalog objects", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The price of the subscription, if STATIC", "readOnly": false, "required": false } ] }, { "name": "SubscriptionPricingType", "properties": [] }, { "name": "CatalogItemOption", "properties": [ { "name": "name", "type": "string", "description": "The item option's display name for the seller. Must be unique across\nall item options. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "display_name", "type": "string", "description": "The item option's display name for the customer. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The item option's human-readable description. Displayed in the Square\nPoint of Sale app for the seller and in the Online Store or on receipts for\nthe buyer. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "show_colors", "type": "boolean", "description": "If true, display colors for entries in `values` when present.", "readOnly": false, "required": false }, { "name": "values", "type": "array", "description": "A list of CatalogObjects containing the\n`CatalogItemOptionValue`s for this item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" } ] }, { "name": "CatalogItemOptionValue", "properties": [ { "name": "item_option_id", "type": "string", "description": "Unique ID of the associated item option.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "Name of this item option value. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "A human-readable description for the option value. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "color", "type": "string", "description": "The HTML-supported hex color for the item option (e.g., \"#ff8d4e85\").\nOnly displayed if `show_colors` is enabled on the parent `ItemOption`. When\nleft unset, `color` defaults to white (\"#ffffff\") when `show_colors` is\nenabled on the parent `ItemOption`.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "Determines where this option value appears in a list of option values.", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinition", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogCustomAttributeDefinitionType", "description": "The type of this custom attribute. Cannot be modified after creation.\nRequired.\n", "readOnly": false, "required": true }, { "name": "name", "type": "string", "description": " The name of this definition for API and seller-facing UI purposes.\nThe name must be unique within the (merchant, application) pair. Required.\nMay not be empty and may not exceed 255 characters. Can be modified after creation.", "readOnly": false, "required": true }, { "name": "description", "type": "string", "description": "Seller-oriented description of the meaning of this Custom Attribute,\nany constraints that the seller should observe, etc. May be displayed as a tooltip in Square UIs.", "readOnly": false, "required": false }, { "name": "source_application", "type": "#/components/schemas/SourceApplication", "description": "__Read only.__ Contains information about the application that\ncreated this custom attribute definition.", "readOnly": false, "required": false }, { "name": "allowed_object_types", "type": "array", "description": "The set of `CatalogObject` types that this custom atttribute may be applied to.\nCurrently, only `ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, and `CATEGORY` are allowed. At least one type must be included.\n", "readOnly": false, "required": true, "arrayType": "#/components/schemas/CatalogObjectType" }, { "name": "seller_visibility", "type": "#/components/schemas/CatalogCustomAttributeDefinitionSellerVisibility", "description": "The visibility of a custom attribute in seller-facing UIs (including Square Point\nof Sale applications and Square Dashboard). May be modified.\n", "readOnly": false, "required": false }, { "name": "app_visibility", "type": "#/components/schemas/CatalogCustomAttributeDefinitionAppVisibility", "description": "The visibility of a custom attribute to applications other than the application\nthat created the attribute.\n", "readOnly": false, "required": false }, { "name": "string_config", "type": "#/components/schemas/CatalogCustomAttributeDefinitionStringConfig", "description": "Optionally, populated when `type` = `STRING`, unset otherwise.", "readOnly": false, "required": false }, { "name": "number_config", "type": "#/components/schemas/CatalogCustomAttributeDefinitionNumberConfig", "description": "Optionally, populated when `type` = `NUMBER`, unset otherwise.", "readOnly": false, "required": false }, { "name": "selection_config", "type": "#/components/schemas/CatalogCustomAttributeDefinitionSelectionConfig", "description": "Populated when `type` is set to `SELECTION`, unset otherwise.", "readOnly": false, "required": false }, { "name": "custom_attribute_usage_count", "type": "integer", "description": "The number of custom attributes that reference this\ncustom attribute definition. Set by the server in response to a ListCatalog\nrequest with `include_counts` set to `true`. If the actual count is greater\nthan 100, `custom_attribute_usage_count` will be set to `100`.", "readOnly": true, "required": false }, { "name": "key", "type": "string", "description": "The name of the desired custom attribute key that can be used to access\nthe custom attribute value on catalog objects. Cannot be modified after the\ncustom attribute definition has been created.\nMust be between 1 and 60 characters, and may only contain the characters `[a-zA-Z0-9_-]`.", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinitionType", "properties": [] }, { "name": "SourceApplication", "properties": [ { "name": "product", "type": "#/components/schemas/Product", "description": "__Read only__ The [product](entity:Product) type of the application.\n", "readOnly": false, "required": false }, { "name": "application_id", "type": "string", "description": "__Read only__ The Square-assigned ID of the application. This field is used only if the\n[product](entity:Product) type is `EXTERNAL_API`.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "__Read only__ The display name of the application\n(for example, `\"Custom Application\"` or `\"Square POS 4.74 for Android\"`).", "readOnly": false, "required": false } ] }, { "name": "Product", "properties": [] }, { "name": "CatalogCustomAttributeDefinitionSellerVisibility", "properties": [] }, { "name": "CatalogCustomAttributeDefinitionAppVisibility", "properties": [] }, { "name": "CatalogCustomAttributeDefinitionStringConfig", "properties": [ { "name": "enforce_uniqueness", "type": "boolean", "description": "If true, each Custom Attribute instance associated with this Custom Attribute\nDefinition must have a unique value within the seller's catalog. For\nexample, this may be used for a value like a SKU that should not be\nduplicated within a seller's catalog. May not be modified after the\ndefinition has been created.", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinitionNumberConfig", "properties": [ { "name": "precision", "type": "integer", "description": "An integer between 0 and 5 that represents the maximum number of\npositions allowed after the decimal in number custom attribute values\nFor example:\n\n- if the precision is 0, the quantity can be 1, 2, 3, etc.\n- if the precision is 1, the quantity can be 0.1, 0.2, etc.\n- if the precision is 2, the quantity can be 0.01, 0.12, etc.\n\nDefault: 5", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinitionSelectionConfig", "properties": [ { "name": "max_allowed_selections", "type": "integer", "description": "The maximum number of selections that can be set. The maximum value for this\nattribute is 100. The default value is 1. The value can be modified, but changing the value will not\naffect existing custom attribute values on objects. Clients need to\nhandle custom attributes with more selected values than allowed by this limit.", "readOnly": false, "required": false }, { "name": "allowed_selections", "type": "array", "description": "The set of valid `CatalogCustomAttributeSelections`. Up to a maximum of 100\nselections can be defined. Can be modified.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection" } ] }, { "name": "CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection", "properties": [ { "name": "uid", "type": "string", "description": "Unique ID set by Square.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "Selection name, unique within `allowed_selections`.", "readOnly": false, "required": true } ] }, { "name": "CatalogQuickAmountsSettings", "properties": [ { "name": "option", "type": "#/components/schemas/CatalogQuickAmountsSettingsOption", "description": "Represents the option seller currently uses on Quick Amounts.\n", "readOnly": false, "required": true }, { "name": "eligible_for_auto_amounts", "type": "boolean", "description": "Represents location's eligibility for auto amounts\nThe boolean should be consistent with whether there are AUTO amounts in the `amounts`.", "readOnly": false, "required": false }, { "name": "amounts", "type": "array", "description": "Represents a set of Quick Amounts at this location.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogQuickAmount" } ] }, { "name": "CatalogQuickAmountsSettingsOption", "properties": [] }, { "name": "CatalogQuickAmount", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogQuickAmountType", "description": "Represents the type of the Quick Amount.\n", "readOnly": false, "required": true }, { "name": "amount", "type": "#/components/schemas/Money", "description": "Represents the actual amount of the Quick Amount with Money type.", "readOnly": false, "required": true }, { "name": "score", "type": "integer", "description": "Describes the ranking of the Quick Amount provided by machine learning model, in the range [0, 100].\nMANUAL type amount will always have score = 100.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The order in which this Quick Amount should be displayed.", "readOnly": false, "required": false } ] }, { "name": "CatalogQuickAmountType", "properties": [] }, { "name": "CatalogSubscriptionPlanVariation", "properties": [ { "name": "name", "type": "string", "description": "The name of the plan variation.", "readOnly": false, "required": true }, { "name": "phases", "type": "array", "description": "A list containing each [SubscriptionPhase](entity:SubscriptionPhase) for this plan variation.", "readOnly": false, "required": true, "arrayType": "#/components/schemas/SubscriptionPhase" }, { "name": "subscription_plan_id", "type": "string", "description": "The id of the subscription plan, if there is one.", "readOnly": false, "required": false }, { "name": "monthly_billing_anchor_date", "type": "integer", "description": "The day of the month the billing period starts.", "readOnly": false, "required": false }, { "name": "can_prorate", "type": "boolean", "description": "Whether bills for this plan variation can be split for proration.", "readOnly": false, "required": false }, { "name": "successor_plan_variation_id", "type": "string", "description": "The ID of a \"successor\" plan variation to this one. If the field is set, and this object is disabled at all\nlocations, it indicates that this variation is deprecated and the object identified by the successor ID be used in\nits stead.", "readOnly": false, "required": false } ] }, { "name": "CatalogAvailabilityPeriod", "properties": [ { "name": "start_local_time", "type": "string", "description": "The start time of an availability period, specified in local time using partial-time\nRFC 3339 format. For example, `8:30:00` for a period starting at 8:30 in the morning.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC.", "readOnly": false, "required": false }, { "name": "end_local_time", "type": "string", "description": "The end time of an availability period, specified in local time using partial-time\nRFC 3339 format. For example, `21:00:00` for a period ending at 9:00 in the evening.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC.", "readOnly": false, "required": false }, { "name": "day_of_week", "type": "#/components/schemas/DayOfWeek", "description": "The day of the week for this availability period.\n", "readOnly": false, "required": false } ] }, { "name": "DayOfWeek", "properties": [] } ], "UpdateCatalogImageRequest": [ { "name": "UpdateCatalogImageRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this UpdateCatalogImage request.\nKeys can be any valid string but must be unique for every UpdateCatalogImage request.\n\nSee [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information.", "readOnly": false, "required": true }, { "name": "image_id", "type": "string", "description": "The ID of the `CatalogImage` object to update the encapsulated image file.", "readOnly": false, "required": true }, { "name": "image_file", "type": "string", "description": "Path to the image file to upload", "readOnly": false, "required": true, "isFile": true } ] } ], "CatalogInfoRequest": [ { "name": "CatalogInfoRequest", "properties": [] } ], "ListCatalogRequest": [ { "name": "ListCatalogRequest", "properties": [ { "name": "cursor", "type": "string", "description": "The pagination cursor returned in the previous response. Leave unset for an initial request.\nThe page size is currently set to be 100.\nSee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.", "readOnly": false, "required": false }, { "name": "types", "type": "string", "description": "An optional case-insensitive, comma-separated list of object types to retrieve.\n\nThe valid values are defined in the [CatalogObjectType](entity:CatalogObjectType) enum, for example,\n`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,\n`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.\n\nIf this is unspecified, the operation returns objects of all the top level types at the version\nof the Square API used to make the request. Object types that are nested onto other object types\nare not included in the defaults.\n\nAt the current API version the default object types are:\nITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, \nPRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,\nSUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The specific version of the catalog objects to be included in the response.\nThis allows you to retrieve historical versions of objects. The specified version value is matched against\nthe [CatalogObject](entity:CatalogObject)s' `version` attribute. If not included, results will be from the\ncurrent version of the catalog.", "readOnly": false, "required": false } ] } ], "UpsertCatalogObjectRequest": [ { "name": "UpsertCatalogObjectRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "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).\n\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.\n\nSee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information.", "readOnly": false, "required": true }, { "name": "object", "type": "#/components/schemas/CatalogObject", "description": "A CatalogObject to be created or updated.\n\n- For updates, the object must be active (the `is_deleted` field is not `true`).\n- For creates, the object ID must start with `#`. The provided ID is replaced with a server-generated ID.", "readOnly": false, "required": true } ] }, { "name": "CatalogObject", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogObjectType", "description": "The type of this object. Each object type has expected\nproperties expressed in a structured format within its corresponding `*_data` field below.\n", "readOnly": false, "required": true }, { "name": "id", "type": "string", "description": "An identifier to reference this object in the catalog. When a new `CatalogObject`\nis inserted, the client should set the id to a temporary identifier starting with\na \"`#`\" character. Other objects being inserted or updated within the same request\nmay use this identifier to refer to the new object.\n\nWhen the server receives the new object, it will supply a unique identifier that\nreplaces the temporary identifier for all future references.", "readOnly": false, "required": true }, { "name": "updated_at", "type": "string", "description": "Last modification [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) in RFC 3339 format, e.g., `\"2016-08-15T23:59:33.123Z\"`\nwould indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "The version of the object. When updating an object, the version supplied\nmust match the version in the database, otherwise the write will be rejected as conflicting.", "readOnly": false, "required": false }, { "name": "is_deleted", "type": "boolean", "description": "If `true`, the object has been deleted from the database. Must be `false` for new objects\nbeing inserted. When deleted, the `updated_at` field will equal the deletion time.", "readOnly": false, "required": false }, { "name": "custom_attribute_values", "type": "map", "description": "A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair\nis a [CatalogCustomAttributeValue](entity:CatalogCustomAttributeValue) object. The key is the `key` attribute\nvalue defined in the associated [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition)\nobject defined by the application making the request.\n\nIf the `CatalogCustomAttributeDefinition` object is\ndefined by another application, the `CatalogCustomAttributeDefinition`'s key attribute value is prefixed by\nthe defining application ID. For example, if the `CatalogCustomAttributeDefinition` has a `key` attribute of\n`\"cocoa_brand\"` and the defining application ID is `\"abcd1234\"`, the key in the map is `\"abcd1234:cocoa_brand\"`\nif the application making the request is different from the application defining the custom attribute definition.\nOtherwise, the key used in the map is simply `\"cocoa_brand\"`.\n\nApplication-defined custom attributes are set at a global (location-independent) level.\nCustom attribute values are intended to store additional information about a catalog object\nor associations with an entity in another system. Do not use custom attributes\nto store any sensitive information (personally identifiable information, card details, etc.).", "readOnly": false, "required": false }, { "name": "catalog_v1_ids", "type": "array", "description": "The Connect v1 IDs for this object at each location where it is present, where they\ndiffer from the object's Connect V2 ID. The field will only be present for objects that\nhave been created or modified by legacy APIs.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogV1Id" }, { "name": "present_at_all_locations", "type": "boolean", "description": "If `true`, this object is present at all locations (including future locations), except where specified in\nthe `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations),\nexcept where specified in the `present_at_location_ids` field. If not specified, defaults to `true`.", "readOnly": false, "required": false }, { "name": "present_at_location_ids", "type": "array", "description": "A list of locations where the object is present, even if `present_at_all_locations` is `false`.\nThis can include locations that are deactivated.", "readOnly": false, "required": false }, { "name": "absent_at_location_ids", "type": "array", "description": "A list of locations where the object is not present, even if `present_at_all_locations` is `true`.\nThis can include locations that are deactivated.", "readOnly": false, "required": false }, { "name": "item_data", "type": "#/components/schemas/CatalogItem", "description": "Structured data for a `CatalogItem`, set for CatalogObjects of type `ITEM`.", "readOnly": false, "required": false }, { "name": "category_data", "type": "#/components/schemas/CatalogCategory", "description": "Structured data for a `CatalogCategory`, set for CatalogObjects of type `CATEGORY`.", "readOnly": false, "required": false }, { "name": "item_variation_data", "type": "#/components/schemas/CatalogItemVariation", "description": "Structured data for a `CatalogItemVariation`, set for CatalogObjects of type `ITEM_VARIATION`.", "readOnly": false, "required": false }, { "name": "tax_data", "type": "#/components/schemas/CatalogTax", "description": "Structured data for a `CatalogTax`, set for CatalogObjects of type `TAX`.", "readOnly": false, "required": false }, { "name": "discount_data", "type": "#/components/schemas/CatalogDiscount", "description": "Structured data for a `CatalogDiscount`, set for CatalogObjects of type `DISCOUNT`.", "readOnly": false, "required": false }, { "name": "modifier_list_data", "type": "#/components/schemas/CatalogModifierList", "description": "Structured data for a `CatalogModifierList`, set for CatalogObjects of type `MODIFIER_LIST`.", "readOnly": false, "required": false }, { "name": "modifier_data", "type": "#/components/schemas/CatalogModifier", "description": "Structured data for a `CatalogModifier`, set for CatalogObjects of type `MODIFIER`.", "readOnly": false, "required": false }, { "name": "time_period_data", "type": "#/components/schemas/CatalogTimePeriod", "description": "Structured data for a `CatalogTimePeriod`, set for CatalogObjects of type `TIME_PERIOD`.", "readOnly": false, "required": false }, { "name": "product_set_data", "type": "#/components/schemas/CatalogProductSet", "description": "Structured data for a `CatalogProductSet`, set for CatalogObjects of type `PRODUCT_SET`.", "readOnly": false, "required": false }, { "name": "pricing_rule_data", "type": "#/components/schemas/CatalogPricingRule", "description": "Structured data for a `CatalogPricingRule`, set for CatalogObjects of type `PRICING_RULE`.\nA `CatalogPricingRule` object often works with a `CatalogProductSet` object or a `CatalogTimePeriod` object.", "readOnly": false, "required": false }, { "name": "image_data", "type": "#/components/schemas/CatalogImage", "description": "Structured data for a `CatalogImage`, set for CatalogObjects of type `IMAGE`.", "readOnly": false, "required": false }, { "name": "measurement_unit_data", "type": "#/components/schemas/CatalogMeasurementUnit", "description": "Structured data for a `CatalogMeasurementUnit`, set for CatalogObjects of type `MEASUREMENT_UNIT`.", "readOnly": false, "required": false }, { "name": "subscription_plan_data", "type": "#/components/schemas/CatalogSubscriptionPlan", "description": "Structured data for a `CatalogSubscriptionPlan`, set for CatalogObjects of type `SUBSCRIPTION_PLAN`.", "readOnly": false, "required": false }, { "name": "item_option_data", "type": "#/components/schemas/CatalogItemOption", "description": "Structured data for a `CatalogItemOption`, set for CatalogObjects of type `ITEM_OPTION`.", "readOnly": false, "required": false }, { "name": "item_option_value_data", "type": "#/components/schemas/CatalogItemOptionValue", "description": "Structured data for a `CatalogItemOptionValue`, set for CatalogObjects of type `ITEM_OPTION_VAL`.", "readOnly": false, "required": false }, { "name": "custom_attribute_definition_data", "type": "#/components/schemas/CatalogCustomAttributeDefinition", "description": "Structured data for a `CatalogCustomAttributeDefinition`, set for CatalogObjects of type `CUSTOM_ATTRIBUTE_DEFINITION`.", "readOnly": false, "required": false }, { "name": "quick_amounts_settings_data", "type": "#/components/schemas/CatalogQuickAmountsSettings", "description": "Structured data for a `CatalogQuickAmountsSettings`, set for CatalogObjects of type `QUICK_AMOUNTS_SETTINGS`.", "readOnly": false, "required": false }, { "name": "subscription_plan_variation_data", "type": "#/components/schemas/CatalogSubscriptionPlanVariation", "description": "Structured data for a `CatalogSubscriptionPlanVariation`, set for CatalogObjects of type `SUBSCRIPTION_PLAN_VARIATION`.", "readOnly": false, "required": false }, { "name": "availability_period_data", "type": "#/components/schemas/CatalogAvailabilityPeriod", "description": "Structured data for a `CatalogAvailabilityPeriod`, set for CatalogObjects of type `AVAILABILITY_PERIOD`.", "readOnly": false, "required": false } ] }, { "name": "CatalogObjectType", "properties": [] }, { "name": "CatalogV1Id", "properties": [ { "name": "catalog_v1_id", "type": "string", "description": "The ID for an object used in the Square API V1, if the object ID differs from the Square API V2 object ID.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the `Location` this Connect V1 ID is associated with.", "readOnly": false, "required": false } ] }, { "name": "CatalogItem", "properties": [ { "name": "name", "type": "string", "description": "The item's name. This is a searchable attribute for use in applicable query filters, its value must not be empty, and the length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The item's description. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.\n\nDeprecated at 2022-07-20, this field is planned to retire in 6 months. You should migrate to use `description_html` to set the description\nof the [CatalogItem](entity:CatalogItem) instance. The `description` and `description_html` field values are kept in sync. If you try to\nset the both fields, the `description_html` text value overwrites the `description` value. Updates in one field are also reflected in the other,\nexcept for when you use an early version before Square API 2022-07-20 and `description_html` is set to blank, setting the `description` value to null\ndoes not nullify `description_html`.", "readOnly": false, "required": false }, { "name": "abbreviation", "type": "string", "description": "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.\nThis attribute is searchable, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "label_color", "type": "string", "description": "The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code.", "readOnly": false, "required": false }, { "name": "is_taxable", "type": "boolean", "description": "Indicates whether the item is taxable (`true`) or non-taxable (`false`). Default is `true`.", "readOnly": false, "required": false }, { "name": "category_id", "type": "string", "description": "The ID of the item's category, if any. Deprecated since 2023-12-13. Use `CatalogItem.categories`, instead.", "readOnly": false, "required": false }, { "name": "tax_ids", "type": "array", "description": "A set of IDs indicating the taxes enabled for\nthis item. When updating an item, any taxes listed here will be added to the item.\nTaxes may also be added to or deleted from an item using `UpdateItemTaxes`.", "readOnly": false, "required": false }, { "name": "modifier_list_info", "type": "array", "description": "A set of `CatalogItemModifierListInfo` objects\nrepresenting the modifier lists that apply to this item, along with the overrides and min\nand max limits that are specific to this item. Modifier lists\nmay also be added to or deleted from an item using `UpdateItemModifierLists`.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemModifierListInfo" }, { "name": "variations", "type": "array", "description": "A list of [CatalogItemVariation](entity:CatalogItemVariation) objects for this item. An item must have\nat least one variation.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" }, { "name": "product_type", "type": "#/components/schemas/CatalogItemProductType", "description": "The product type of the item. Once set, the `product_type` value cannot be modified.\n\nItems of the `LEGACY_SQUARE_ONLINE_SERVICE` and `LEGACY_SQUARE_ONLINE_MEMBERSHIP` product types can be updated\nbut cannot be created using the API.\n", "readOnly": false, "required": false }, { "name": "skip_modifier_screen", "type": "boolean", "description": "If `false`, the Square Point of Sale app will present the `CatalogItem`'s\ndetails screen immediately, allowing the merchant to choose `CatalogModifier`s\nbefore adding the item to the cart. This is the default behavior.\n\nIf `true`, the Square Point of Sale app will immediately add the item to the cart with the pre-selected\nmodifiers, and merchants can edit modifiers by drilling down onto the item's details.\n\nThird-party clients are encouraged to implement similar behaviors.", "readOnly": false, "required": false }, { "name": "item_options", "type": "array", "description": "List of item options IDs for this item. Used to manage and group item\nvariations in a specified order.\n\nMaximum: 6 item options.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemOptionForItem" }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogItem` instance.\nThese images will be shown to customers in Square Online Store.\nThe first image will show up as the icon for this item in POS.", "readOnly": false, "required": false }, { "name": "sort_name", "type": "string", "description": "A name to sort the item by. If this name is unspecified, namely, the `sort_name` field is absent, the regular `name` field is used for sorting.\nIts value must not be empty.\n\nIt is currently supported for sellers of the Japanese locale only.", "readOnly": false, "required": false }, { "name": "categories", "type": "array", "description": "The list of categories.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObjectCategory" }, { "name": "description_html", "type": "string", "description": "The item's description as expressed in valid HTML elements. The length of this field value, including those of HTML tags,\nis of Unicode points. With application query filters, the text values of the HTML elements and attributes are searchable. Invalid or\nunsupported HTML elements or attributes are ignored.\n\nSupported HTML elements include:\n- `a`: Link. Supports linking to website URLs, email address, and telephone numbers.\n- `b`, `strong`: Bold text\n- `br`: Line break\n- `code`: Computer code\n- `div`: Section\n- `h1-h6`: Headings\n- `i`, `em`: Italics\n- `li`: List element\n- `ol`: Numbered list\n- `p`: Paragraph\n- `ul`: Bullet list\n- `u`: Underline\n\n\nSupported HTML attributes include:\n- `align`: Alignment of the text content\n- `href`: Link destination\n- `rel`: Relationship between link's target and source\n- `target`: Place to open the linked document", "readOnly": false, "required": false }, { "name": "description_plaintext", "type": "string", "description": "A server-generated plaintext version of the `description_html` field, without formatting tags.", "readOnly": true, "required": false }, { "name": "channels", "type": "array", "description": "A list of IDs representing channels, such as a Square Online site, where the item can be made visible or available.\nThis field is read only and cannot be edited.", "readOnly": false, "required": false }, { "name": "is_archived", "type": "boolean", "description": "Indicates whether this item is archived (`true`) or not (`false`).", "readOnly": false, "required": false }, { "name": "ecom_seo_data", "type": "#/components/schemas/CatalogEcomSeoData", "description": "The SEO data for a seller's Square Online store.", "readOnly": false, "required": false }, { "name": "food_and_beverage_details", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetails", "description": "The food and beverage-specific details for the `FOOD_AND_BEV` item.", "readOnly": false, "required": false }, { "name": "reporting_category", "type": "#/components/schemas/CatalogObjectCategory", "description": "The item's reporting category.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemModifierListInfo", "properties": [ { "name": "modifier_list_id", "type": "string", "description": "The ID of the `CatalogModifierList` controlled by this `CatalogModifierListInfo`.", "readOnly": false, "required": true }, { "name": "modifier_overrides", "type": "array", "description": "A set of `CatalogModifierOverride` objects that override whether a given `CatalogModifier` is enabled by default.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogModifierOverride" }, { "name": "min_selected_modifiers", "type": "integer", "description": "If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`", "readOnly": false, "required": false }, { "name": "max_selected_modifiers", "type": "integer", "description": "If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "If `true`, enable this `CatalogModifierList`. The default value is `true`.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The position of this `CatalogItemModifierListInfo` object within the `modifier_list_info` list applied \nto a `CatalogItem` instance.", "readOnly": false, "required": false } ] }, { "name": "CatalogModifierOverride", "properties": [ { "name": "modifier_id", "type": "string", "description": "The ID of the `CatalogModifier` whose default behavior is being overridden.", "readOnly": false, "required": true }, { "name": "on_by_default", "type": "boolean", "description": "If `true`, this `CatalogModifier` should be selected by default for this `CatalogItem`.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemProductType", "properties": [] }, { "name": "CatalogItemOptionForItem", "properties": [ { "name": "item_option_id", "type": "string", "description": "The unique id of the item option, used to form the dimensions of the item option matrix in a specified order.", "readOnly": false, "required": false } ] }, { "name": "CatalogObjectCategory", "properties": [ { "name": "id", "type": "string", "description": "The ID of the object's category.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The order of the object within the context of the category.", "readOnly": false, "required": false } ] }, { "name": "CatalogEcomSeoData", "properties": [ { "name": "page_title", "type": "string", "description": "The SEO title used for the Square Online store.", "readOnly": false, "required": false }, { "name": "page_description", "type": "string", "description": "The SEO description used for the Square Online store.", "readOnly": false, "required": false }, { "name": "permalink", "type": "string", "description": "The SEO permalink used for the Square Online store.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemFoodAndBeverageDetails", "properties": [ { "name": "calorie_count", "type": "integer", "description": "The calorie count (in the unit of kcal) for the `FOOD_AND_BEV` type of items.", "readOnly": false, "required": false }, { "name": "dietary_preferences", "type": "array", "description": "The dietary preferences for the `FOOD_AND_BEV` item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreference" }, { "name": "ingredients", "type": "array", "description": "The ingredients for the `FOOD_AND_BEV` type item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemFoodAndBeverageDetailsIngredient" } ] }, { "name": "CatalogItemFoodAndBeverageDetailsDietaryPreference", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "description": "The dietary preference type. Supported values include `STANDARD` and `CUSTOM` as specified in `FoodAndBeverageDetails.DietaryPreferenceType`.\n", "readOnly": false, "required": false }, { "name": "standard_name", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference", "description": "The name of the dietary preference from a standard pre-defined list. This should be null if it's a custom dietary preference.\n", "readOnly": false, "required": false }, { "name": "custom_name", "type": "string", "description": "The name of a user-defined custom dietary preference. This should be null if it's a standard dietary preference.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "properties": [] }, { "name": "CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference", "properties": [] }, { "name": "CatalogItemFoodAndBeverageDetailsIngredient", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "description": "The dietary preference type of the ingredient. Supported values include `STANDARD` and `CUSTOM` as specified in `FoodAndBeverageDetails.DietaryPreferenceType`.\n", "readOnly": false, "required": false }, { "name": "standard_name", "type": "#/components/schemas/CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient", "description": "The name of the ingredient from a standard pre-defined list. This should be null if it's a custom dietary preference.\n", "readOnly": false, "required": false }, { "name": "custom_name", "type": "string", "description": "The name of a custom user-defined ingredient. This should be null if it's a standard dietary preference.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient", "properties": [] }, { "name": "CatalogCategory", "properties": [ { "name": "name", "type": "string", "description": "The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogCategory` instance.\nCurrently these images are not displayed by Square, but are free to be displayed in 3rd party applications.", "readOnly": false, "required": false }, { "name": "category_type", "type": "#/components/schemas/CatalogCategoryType", "description": "The type of the category.\n", "readOnly": false, "required": false }, { "name": "parent_category", "type": "#/components/schemas/CatalogObjectCategory", "description": "The ID of the parent category of this category instance.", "readOnly": false, "required": false }, { "name": "is_top_level", "type": "boolean", "description": "Indicates whether a category is a top level category, which does not have any parent_category.", "readOnly": false, "required": false }, { "name": "channels", "type": "array", "description": "A list of IDs representing channels, such as a Square Online site, where the category can be made visible.", "readOnly": false, "required": false }, { "name": "availability_period_ids", "type": "array", "description": "The IDs of the `CatalogAvailabilityPeriod` objects associated with the category.", "readOnly": false, "required": false }, { "name": "online_visibility", "type": "boolean", "description": "Indicates whether the category is visible (`true`) or hidden (`false`) on all of the seller's Square Online sites.", "readOnly": false, "required": false }, { "name": "root_category", "type": "string", "description": "The top-level category in a category hierarchy.", "readOnly": true, "required": false }, { "name": "ecom_seo_data", "type": "#/components/schemas/CatalogEcomSeoData", "description": "The SEO data for a seller's Square Online store.", "readOnly": false, "required": false }, { "name": "path_to_root", "type": "array", "description": "The path from the category to its root category. The first node of the path is the parent of the category\nand the last is the root category. The path is empty if the category is a root category.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CategoryPathToRootNode" } ] }, { "name": "CatalogCategoryType", "properties": [] }, { "name": "CategoryPathToRootNode", "properties": [ { "name": "category_id", "type": "string", "description": "The category's ID.", "readOnly": false, "required": false }, { "name": "category_name", "type": "string", "description": "The category's name.", "readOnly": false, "required": false } ] }, { "name": "CatalogItemVariation", "properties": [ { "name": "item_id", "type": "string", "description": "The ID of the `CatalogItem` associated with this item variation.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The item variation's name. This is a searchable attribute for use in applicable query filters.\n\nIts value has a maximum length of 255 Unicode code points. However, when the parent [item](entity:CatalogItem)\nuses [item options](entity:CatalogItemOption), this attribute is auto-generated, read-only, and can be\nlonger than 255 Unicode code points.", "readOnly": false, "required": false }, { "name": "sku", "type": "string", "description": "The item variation's SKU, if any. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "upc", "type": "string", "description": "The universal product code (UPC) of the item variation, if any. This is a searchable attribute for use in applicable query filters.\n\nThe value of this attribute should be a number of 12-14 digits long. This restriction is enforced on the Square Seller Dashboard,\nSquare Point of Sale or Retail Point of Sale apps, where this attribute shows in the GTIN field. If a non-compliant UPC value is assigned\nto this attribute using the API, the value is not editable on the Seller Dashboard, Square Point of Sale or Retail Point of Sale apps\nunless it is updated to fit the expected format.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal\nfor each item variation within a parent `CatalogItem` is set according to the item variations's\nposition. On reads, the value is not guaranteed to be sequential or unique.", "readOnly": true, "required": false }, { "name": "pricing_type", "type": "#/components/schemas/CatalogPricingType", "description": "Indicates whether the item variation's price is fixed or determined at the time\nof sale.\n", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The item variation's price, if fixed pricing is used.", "readOnly": false, "required": false }, { "name": "location_overrides", "type": "array", "description": "Per-location price and inventory overrides.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/ItemVariationLocationOverrides" }, { "name": "track_inventory", "type": "boolean", "description": "If `true`, inventory tracking is active for the variation.", "readOnly": false, "required": false }, { "name": "inventory_alert_type", "type": "#/components/schemas/InventoryAlertType", "description": "Indicates whether the item variation displays an alert when its inventory quantity is less than or equal\nto its `inventory_alert_threshold`.\n", "readOnly": false, "required": false }, { "name": "inventory_alert_threshold", "type": "integer", "description": "If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`\nis `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.\n\nThis value is always an integer.", "readOnly": false, "required": false }, { "name": "user_data", "type": "string", "description": "Arbitrary user metadata to associate with the item variation. This attribute value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "service_duration", "type": "integer", "description": "If the `CatalogItem` that owns this item variation is of type\n`APPOINTMENTS_SERVICE`, then this is the duration of the service in milliseconds. For\nexample, a 30 minute appointment would have the value `1800000`, which is equal to\n30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second).", "readOnly": false, "required": false }, { "name": "available_for_booking", "type": "boolean", "description": "If the `CatalogItem` that owns this item variation is of type\n`APPOINTMENTS_SERVICE`, a bool representing whether this service is available for booking.", "readOnly": false, "required": false }, { "name": "item_option_values", "type": "array", "description": "List of item option values associated with this item variation. Listed\nin the same order as the item options of the parent item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemOptionValueForItemVariation" }, { "name": "measurement_unit_id", "type": "string", "description": "ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity\nsold of this item variation. If left unset, the item will be sold in\nwhole quantities.", "readOnly": false, "required": false }, { "name": "sellable", "type": "boolean", "description": "Whether this variation can be sold. The inventory count of a sellable variation indicates\nthe number of units available for sale. When a variation is both stockable and sellable,\nits sellable inventory count can be smaller than or equal to its stockable count.", "readOnly": false, "required": false }, { "name": "stockable", "type": "boolean", "description": "Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE).\nWhen a variation is both stockable and sellable, the inventory count of a stockable variation keeps track of the number of units of this variation in stock\nand is not an indicator of the number of units of the variation that can be sold.", "readOnly": false, "required": false }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogItemVariation` instance.\nThese images will be shown to customers in Square Online Store.", "readOnly": false, "required": false }, { "name": "team_member_ids", "type": "array", "description": "Tokens of employees that can perform the service represented by this variation. Only valid for\nvariations of type `APPOINTMENTS_SERVICE`.", "readOnly": false, "required": false }, { "name": "stockable_conversion", "type": "#/components/schemas/CatalogStockConversion", "description": "The unit conversion rule, as prescribed by the [CatalogStockConversion](entity:CatalogStockConversion) type,\nthat describes how this non-stockable (i.e., sellable/receivable) item variation is converted\nto/from the stockable item variation sharing the same parent item. With the stock conversion,\nyou can accurately track inventory when an item variation is sold in one unit, but stocked in\nanother unit.", "readOnly": false, "required": false } ] }, { "name": "CatalogPricingType", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "ItemVariationLocationOverrides", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the `Location`. This can include locations that are deactivated.", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The price of the `CatalogItemVariation` at the given `Location`, or blank for variable pricing.", "readOnly": false, "required": false }, { "name": "pricing_type", "type": "#/components/schemas/CatalogPricingType", "description": "The pricing type (fixed or variable) for the `CatalogItemVariation` at the given `Location`.\n", "readOnly": false, "required": false }, { "name": "track_inventory", "type": "boolean", "description": "If `true`, inventory tracking is active for the `CatalogItemVariation` at this `Location`.", "readOnly": false, "required": false }, { "name": "inventory_alert_type", "type": "#/components/schemas/InventoryAlertType", "description": "Indicates whether the `CatalogItemVariation` displays an alert when its inventory\nquantity is less than or equal to its `inventory_alert_threshold`.\n", "readOnly": false, "required": false }, { "name": "inventory_alert_threshold", "type": "integer", "description": "If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`\nis `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.\n\nThis value is always an integer.", "readOnly": false, "required": false }, { "name": "sold_out", "type": "boolean", "description": "Indicates whether the overridden item variation is sold out at the specified location.\n\nWhen inventory tracking is enabled on the item variation either globally or at the specified location,\nthe item variation is automatically marked as sold out when its inventory count reaches zero. The seller\ncan manually set the item variation as sold out even when the inventory count is greater than zero.\nAttempts by an application to set this attribute are ignored. Regardless how the sold-out status is set,\napplications should treat its inventory count as zero when this attribute value is `true`.", "readOnly": true, "required": false }, { "name": "sold_out_valid_until", "type": "string", "description": "The seller-assigned timestamp, of the RFC 3339 format, to indicate when this sold-out variation\nbecomes available again at the specified location. Attempts by an application to set this attribute are ignored.\nWhen the current time is later than this attribute value, the affected item variation is no longer sold out.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "InventoryAlertType", "properties": [] }, { "name": "CatalogItemOptionValueForItemVariation", "properties": [ { "name": "item_option_id", "type": "string", "description": "The unique id of an item option.", "readOnly": false, "required": false }, { "name": "item_option_value_id", "type": "string", "description": "The unique id of the selected value for the item option.", "readOnly": false, "required": false } ] }, { "name": "CatalogStockConversion", "properties": [ { "name": "stockable_item_variation_id", "type": "string", "description": "References to the stockable [CatalogItemVariation](entity:CatalogItemVariation)\nfor this stock conversion. Selling, receiving or recounting the non-stockable `CatalogItemVariation`\ndefined with a stock conversion results in adjustments of this stockable `CatalogItemVariation`.\nThis immutable field must reference a stockable `CatalogItemVariation`\nthat shares the parent [CatalogItem](entity:CatalogItem) of the converted `CatalogItemVariation.`", "readOnly": false, "required": true }, { "name": "stockable_quantity", "type": "string", "description": "The quantity of the stockable item variation (as identified by `stockable_item_variation_id`)\nequivalent to the non-stockable item variation quantity (as specified in `nonstockable_quantity`)\nas defined by this stock conversion. It accepts a decimal number in a string format that can take\nup to 10 digits before the decimal point and up to 5 digits after the decimal point.", "readOnly": false, "required": true }, { "name": "nonstockable_quantity", "type": "string", "description": "The converted equivalent quantity of the non-stockable [CatalogItemVariation](entity:CatalogItemVariation)\nin its measurement unit. The `stockable_quantity` value and this `nonstockable_quantity` value together\ndefine the conversion ratio between stockable item variation and the non-stockable item variation.\nIt accepts a decimal number in a string format that can take up to 10 digits before the decimal point\nand up to 5 digits after the decimal point.", "readOnly": false, "required": true } ] }, { "name": "CatalogTax", "properties": [ { "name": "name", "type": "string", "description": "The tax's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/TaxCalculationPhase", "description": "Whether the tax is calculated based on a payment's subtotal or total.\n", "readOnly": false, "required": false }, { "name": "inclusion_type", "type": "#/components/schemas/TaxInclusionType", "description": "Whether the tax is `ADDITIVE` or `INCLUSIVE`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign.\nA value of `7.5` corresponds to 7.5%. For a location-specific tax rate, contact the tax authority of the location or a tax consultant.", "readOnly": false, "required": false }, { "name": "applies_to_custom_amounts", "type": "boolean", "description": "If `true`, the fee applies to custom amounts entered into the Square Point of Sale\napp that are not associated with a particular `CatalogItem`.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "A Boolean flag to indicate whether the tax is displayed as enabled (`true`) in the Square Point of Sale app or not (`false`).", "readOnly": false, "required": false }, { "name": "applies_to_product_set_id", "type": "string", "description": "The ID of a `CatalogProductSet` object. If set, the tax is applicable to all products in the product set.", "readOnly": false, "required": false } ] }, { "name": "TaxCalculationPhase", "properties": [] }, { "name": "TaxInclusionType", "properties": [] }, { "name": "CatalogDiscount", "properties": [ { "name": "name", "type": "string", "description": "The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "discount_type", "type": "#/components/schemas/CatalogDiscountType", "description": "Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the discount as a string representation of a decimal number, using a `.` as the decimal\nseparator and without a `%` sign. A value of `7.5` corresponds to `7.5%`. Specify a percentage of `0` if `discount_type`\nis `VARIABLE_PERCENTAGE`.\n\nDo not use this field for amount-based or variable discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of the discount. Specify an amount of `0` if `discount_type` is `VARIABLE_AMOUNT`.\n\nDo not use this field for percentage-based or variable discounts.", "readOnly": false, "required": false }, { "name": "pin_required", "type": "boolean", "description": "Indicates whether a mobile staff member needs to enter their PIN to apply the\ndiscount to a payment in the Square Point of Sale app.", "readOnly": false, "required": false }, { "name": "label_color", "type": "string", "description": "The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code.", "readOnly": false, "required": false }, { "name": "modify_tax_basis", "type": "#/components/schemas/CatalogDiscountModifyTaxBasis", "description": "Indicates whether this discount should reduce the price used to calculate tax.\n\nMost discounts should use `MODIFY_TAX_BASIS`. However, in some circumstances taxes must\nbe calculated based on an item's price, ignoring a particular discount. For example,\nin many US jurisdictions, a manufacturer coupon or instant rebate reduces the price a\ncustomer pays but does not reduce the sale price used to calculate how much sales tax is\ndue. In this case, the discount representing that manufacturer coupon should have\n`DO_NOT_MODIFY_TAX_BASIS` for this field.\n\nIf you are unsure whether you need to use this field, consult your tax professional.\n", "readOnly": false, "required": false }, { "name": "maximum_amount_money", "type": "#/components/schemas/Money", "description": "For a percentage discount, the maximum absolute value of the discount. For example, if a\n50% discount has a `maximum_amount_money` of $20, a $100 purchase will yield a $20 discount,\nnot a $50 discount.", "readOnly": false, "required": false } ] }, { "name": "CatalogDiscountType", "properties": [] }, { "name": "CatalogDiscountModifyTaxBasis", "properties": [] }, { "name": "CatalogModifierList", "properties": [ { "name": "name", "type": "string", "description": "The name of the `CatalogModifierList` instance. This is a searchable attribute for use in applicable query filters, and its value length is of \nUnicode code points.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The position of this `CatalogModifierList` within a list of `CatalogModifierList` instances.", "readOnly": false, "required": false }, { "name": "selection_type", "type": "#/components/schemas/CatalogModifierListSelectionType", "description": "Indicates whether a single (`SINGLE`) or multiple (`MULTIPLE`) modifiers from the list\ncan be applied to a single `CatalogItem`.\n\nFor text-based modifiers, the `selection_type` attribute is always `SINGLE`. The other value is ignored.\n", "readOnly": false, "required": false }, { "name": "modifiers", "type": "array", "description": "A non-empty list of `CatalogModifier` objects to be included in the `CatalogModifierList`, \nfor non text-based modifiers when the `modifier_type` attribute is `LIST`. Each element of this list \nis a `CatalogObject` instance of the `MODIFIER` type, containing the following attributes:\n```\n{\n\"id\": \"{{catalog_modifier_id}}\",\n\"type\": \"MODIFIER\", \n\"modifier_data\": {{a CatalogModifier instance>}} \n}\n```", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" }, { "name": "image_ids", "type": "array", "description": "The IDs of images associated with this `CatalogModifierList` instance.\nCurrently these images are not displayed on Square products, but may be displayed in 3rd-party applications.", "readOnly": false, "required": false }, { "name": "modifier_type", "type": "#/components/schemas/CatalogModifierListModifierType", "description": "The type of the modifier. \n\nWhen this `modifier_type` value is `TEXT`, the `CatalogModifierList` represents a text-based modifier. \nWhen this `modifier_type` value is `LIST`, the `CatalogModifierList` contains a list of `CatalogModifier` objects.\n", "readOnly": false, "required": false }, { "name": "max_length", "type": "integer", "description": "The maximum length, in Unicode points, of the text string of the text-based modifier as represented by \nthis `CatalogModifierList` object with the `modifier_type` set to `TEXT`.", "readOnly": false, "required": false }, { "name": "text_required", "type": "boolean", "description": "Whether the text string must be a non-empty string (`true`) or not (`false`) for a text-based modifier\nas represented by this `CatalogModifierList` object with the `modifier_type` set to `TEXT`.", "readOnly": false, "required": false }, { "name": "internal_name", "type": "string", "description": "A note for internal use by the business. \n\nFor example, for a text-based modifier applied to a T-shirt item, if the buyer-supplied text of \"Hello, Kitty!\" \nis to be printed on the T-shirt, this `internal_name` attribute can be \"Use italic face\" as \nan instruction for the business to follow. \n\nFor non text-based modifiers, this `internal_name` attribute can be \nused to include SKUs, internal codes, or supplemental descriptions for internal use.", "readOnly": false, "required": false } ] }, { "name": "CatalogModifierListSelectionType", "properties": [] }, { "name": "CatalogModifierListModifierType", "properties": [] }, { "name": "CatalogModifier", "properties": [ { "name": "name", "type": "string", "description": "The modifier name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The modifier price.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "Determines where this `CatalogModifier` appears in the `CatalogModifierList`.", "readOnly": false, "required": false }, { "name": "modifier_list_id", "type": "string", "description": "The ID of the `CatalogModifierList` associated with this modifier.", "readOnly": false, "required": false }, { "name": "location_overrides", "type": "array", "description": "Location-specific price overrides.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/ModifierLocationOverrides" }, { "name": "image_id", "type": "string", "description": "The ID of the image associated with this `CatalogModifier` instance.\nCurrently this image is not displayed by Square, but is free to be displayed in 3rd party applications.", "readOnly": false, "required": false } ] }, { "name": "ModifierLocationOverrides", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the `Location` object representing the location. This can include a deactivated location.", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The overridden price at the specified location. If this is unspecified, the modifier price is not overridden.\nThe modifier becomes free of charge at the specified location, when this `price_money` field is set to 0.", "readOnly": false, "required": false }, { "name": "sold_out", "type": "boolean", "description": "Indicates whether the modifier is sold out at the specified location or not. As an example, for cheese (modifier) burger (item), when the modifier is sold out, it is the cheese, but not the burger, that is sold out.\nThe seller can manually set this sold out status. Attempts by an application to set this attribute are ignored.", "readOnly": true, "required": false } ] }, { "name": "CatalogTimePeriod", "properties": [ { "name": "event", "type": "string", "description": "An iCalendar (RFC 5545) [event](https://tools.ietf.org/html/rfc5545#section-3.6.1), which\nspecifies the name, timing, duration and recurrence of this time period.\n\nExample:\n\n```\nDTSTART:20190707T180000\nDURATION:P2H\nRRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR\n```\n\nOnly `SUMMARY`, `DTSTART`, `DURATION` and `RRULE` fields are supported.\n`DTSTART` must be in local (unzoned) time format. Note that while `BEGIN:VEVENT`\nand `END:VEVENT` is not required in the request. The response will always\ninclude them.", "readOnly": false, "required": false } ] }, { "name": "CatalogProductSet", "properties": [ { "name": "name", "type": "string", "description": "User-defined name for the product set. For example, \"Clearance Items\"\nor \"Winter Sale Items\".", "readOnly": false, "required": false }, { "name": "product_ids_any", "type": "array", "description": " Unique IDs for any `CatalogObject` included in this product set. Any\nnumber of these catalog objects can be in an order for a pricing rule to apply.\n\nThis can be used with `product_ids_all` in a parent `CatalogProductSet` to\nmatch groups of products for a bulk discount, such as a discount for an\nentree and side combo.\n\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.\n\nMax: 500 catalog object IDs.", "readOnly": false, "required": false }, { "name": "product_ids_all", "type": "array", "description": "Unique IDs for any `CatalogObject` included in this product set.\nAll objects in this set must be included in an order for a pricing rule to apply.\n\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.\n\nMax: 500 catalog object IDs.", "readOnly": false, "required": false }, { "name": "quantity_exact", "type": "integer", "description": "If set, there must be exactly this many items from `products_any` or `products_all`\nin the cart for the discount to apply.\n\nCannot be combined with either `quantity_min` or `quantity_max`.", "readOnly": false, "required": false }, { "name": "quantity_min", "type": "integer", "description": "If set, there must be at least this many items from `products_any` or `products_all`\nin a cart for the discount to apply. See `quantity_exact`. Defaults to 0 if\n`quantity_exact`, `quantity_min` and `quantity_max` are all unspecified.", "readOnly": false, "required": false }, { "name": "quantity_max", "type": "integer", "description": "If set, the pricing rule will apply to a maximum of this many items from\n`products_any` or `products_all`.", "readOnly": false, "required": false }, { "name": "all_products", "type": "boolean", "description": "If set to `true`, the product set will include every item in the catalog.\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.", "readOnly": false, "required": false } ] }, { "name": "CatalogPricingRule", "properties": [ { "name": "name", "type": "string", "description": "User-defined name for the pricing rule. For example, \"Buy one get one\nfree\" or \"10% off\".", "readOnly": false, "required": false }, { "name": "time_period_ids", "type": "array", "description": "A list of unique IDs for the catalog time periods when\nthis pricing rule is in effect. If left unset, the pricing rule is always\nin effect.", "readOnly": false, "required": false }, { "name": "discount_id", "type": "string", "description": "Unique ID for the `CatalogDiscount` to take off\nthe price of all matched items.", "readOnly": false, "required": false }, { "name": "match_products_id", "type": "string", "description": "Unique ID for the `CatalogProductSet` that will be matched by this rule. A match rule\nmatches within the entire cart, and can match multiple times. This field will always be set.", "readOnly": false, "required": false }, { "name": "apply_products_id", "type": "string", "description": "__Deprecated__: Please use the `exclude_products_id` field to apply\nan exclude set instead. Exclude sets allow better control over quantity\nranges and offer more flexibility for which matched items receive a discount.\n\n`CatalogProductSet` to apply the pricing to.\nAn apply rule matches within the subset of the cart that fits the match rules (the match set).\nAn apply rule can only match once in the match set.\nIf not supplied, the pricing will be applied to all products in the match set.\nOther products retain their base price, or a price generated by other rules.", "readOnly": false, "required": false }, { "name": "exclude_products_id", "type": "string", "description": "`CatalogProductSet` to exclude from the pricing rule.\nAn exclude rule matches within the subset of the cart that fits the match rules (the match set).\nAn exclude rule can only match once in the match set.\nIf not supplied, the pricing will be applied to all products in the match set.\nOther products retain their base price, or a price generated by other rules.", "readOnly": false, "required": false }, { "name": "valid_from_date", "type": "string", "description": "Represents the date the Pricing Rule is valid from. Represented in RFC 3339 full-date format (YYYY-MM-DD).", "readOnly": false, "required": false }, { "name": "valid_from_local_time", "type": "string", "description": "Represents the local time the pricing rule should be valid from. Represented in RFC 3339 partial-time format\n(HH:MM:SS). Partial seconds will be truncated.", "readOnly": false, "required": false }, { "name": "valid_until_date", "type": "string", "description": "Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD).", "readOnly": false, "required": false }, { "name": "valid_until_local_time", "type": "string", "description": "Represents the local time the pricing rule should be valid until. Represented in RFC 3339 partial-time format\n(HH:MM:SS). Partial seconds will be truncated.", "readOnly": false, "required": false }, { "name": "exclude_strategy", "type": "#/components/schemas/ExcludeStrategy", "description": "If an `exclude_products_id` was given, controls which subset of matched\nproducts is excluded from any discounts.\n\nDefault value: `LEAST_EXPENSIVE`\n", "readOnly": false, "required": false }, { "name": "minimum_order_subtotal_money", "type": "#/components/schemas/Money", "description": "The minimum order subtotal (before discounts or taxes are applied)\nthat must be met before this rule may be applied.", "readOnly": false, "required": false }, { "name": "customer_group_ids_any", "type": "array", "description": "A list of IDs of customer groups, the members of which are eligible for discounts specified in this pricing rule.\nNotice that a group ID is generated by the Customers API.\nIf this field is not set, the specified discount applies to matched products sold to anyone whether the buyer\nhas a customer profile created or not. If this `customer_group_ids_any` field is set, the specified discount\napplies only to matched products sold to customers belonging to the specified customer groups.", "readOnly": false, "required": false } ] }, { "name": "ExcludeStrategy", "properties": [] }, { "name": "CatalogImage", "properties": [ { "name": "name", "type": "string", "description": "The internal name to identify this image in calls to the Square API.\nThis is a searchable attribute for use in applicable query filters\nusing the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).\nIt is not unique and should not be shown in a buyer facing context.", "readOnly": false, "required": false }, { "name": "url", "type": "string", "description": "The URL of this image, generated by Square after an image is uploaded\nusing the [CreateCatalogImage](api-endpoint:Catalog-CreateCatalogImage) endpoint.\nTo modify the image, use the UpdateCatalogImage endpoint. Do not change the URL field.", "readOnly": false, "required": false }, { "name": "caption", "type": "string", "description": "A caption that describes what is shown in the image. Displayed in the\nSquare Online Store. This is a searchable attribute for use in applicable query filters\nusing the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).", "readOnly": false, "required": false }, { "name": "photo_studio_order_id", "type": "string", "description": "The immutable order ID for this image object created by the Photo Studio service in Square Online Store.", "readOnly": false, "required": false } ] }, { "name": "CatalogMeasurementUnit", "properties": [ { "name": "measurement_unit", "type": "#/components/schemas/MeasurementUnit", "description": "Indicates the unit used to measure the quantity of a catalog item variation.", "readOnly": false, "required": false }, { "name": "precision", "type": "integer", "description": "An integer between 0 and 5 that represents the maximum number of\npositions allowed after the decimal in quantities measured with this unit.\nFor example:\n\n- if the precision is 0, the quantity can be 1, 2, 3, etc.\n- if the precision is 1, the quantity can be 0.1, 0.2, etc.\n- if the precision is 2, the quantity can be 0.01, 0.12, etc.\n\nDefault: 3", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnit", "properties": [ { "name": "custom_unit", "type": "#/components/schemas/MeasurementUnitCustom", "description": "A custom unit of measurement defined by the seller using the Point of Sale\napp or ad-hoc as an order line item.", "readOnly": false, "required": false }, { "name": "area_unit", "type": "#/components/schemas/MeasurementUnitArea", "description": "Represents a standard area unit.\n", "readOnly": false, "required": false }, { "name": "length_unit", "type": "#/components/schemas/MeasurementUnitLength", "description": "Represents a standard length unit.\n", "readOnly": false, "required": false }, { "name": "volume_unit", "type": "#/components/schemas/MeasurementUnitVolume", "description": "Represents a standard volume unit.\n", "readOnly": false, "required": false }, { "name": "weight_unit", "type": "#/components/schemas/MeasurementUnitWeight", "description": "Represents a standard unit of weight or mass.\n", "readOnly": false, "required": false }, { "name": "generic_unit", "type": "#/components/schemas/MeasurementUnitGeneric", "description": "Reserved for API integrations that lack the ability to specify a real measurement unit\n", "readOnly": false, "required": false }, { "name": "time_unit", "type": "#/components/schemas/MeasurementUnitTime", "description": "Represents a standard unit of time.\n", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/MeasurementUnitUnitType", "description": "Represents the type of the measurement unit.\n", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnitCustom", "properties": [ { "name": "name", "type": "string", "description": "The name of the custom unit, for example \"bushel\".", "readOnly": false, "required": true }, { "name": "abbreviation", "type": "string", "description": "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears\nin the cart for the Point of Sale app, and in reports.", "readOnly": false, "required": true } ] }, { "name": "MeasurementUnitArea", "properties": [] }, { "name": "MeasurementUnitLength", "properties": [] }, { "name": "MeasurementUnitVolume", "properties": [] }, { "name": "MeasurementUnitWeight", "properties": [] }, { "name": "MeasurementUnitGeneric", "properties": [] }, { "name": "MeasurementUnitTime", "properties": [] }, { "name": "MeasurementUnitUnitType", "properties": [] }, { "name": "CatalogSubscriptionPlan", "properties": [ { "name": "name", "type": "string", "description": "The name of the plan.", "readOnly": false, "required": true }, { "name": "phases", "type": "array", "description": "A list of SubscriptionPhase containing the [SubscriptionPhase](entity:SubscriptionPhase) for this plan.\nThis field it required. Not including this field will throw a REQUIRED_FIELD_MISSING error", "readOnly": false, "required": false, "arrayType": "#/components/schemas/SubscriptionPhase" }, { "name": "subscription_plan_variations", "type": "array", "description": "The list of subscription plan variations available for this product", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" }, { "name": "eligible_item_ids", "type": "array", "description": "The list of IDs of `CatalogItems` that are eligible for subscription by this SubscriptionPlan's variations.", "readOnly": false, "required": false }, { "name": "eligible_category_ids", "type": "array", "description": "The list of IDs of `CatalogCategory` that are eligible for subscription by this SubscriptionPlan's variations.", "readOnly": false, "required": false }, { "name": "all_items", "type": "boolean", "description": "If true, all items in the merchant's catalog are subscribable by this SubscriptionPlan.", "readOnly": false, "required": false } ] }, { "name": "SubscriptionPhase", "properties": [ { "name": "uid", "type": "string", "description": "The Square-assigned ID of the subscription phase. This field cannot be changed after a `SubscriptionPhase` is created.", "readOnly": false, "required": false }, { "name": "cadence", "type": "#/components/schemas/SubscriptionCadence", "description": "The billing cadence of the phase. For example, weekly or monthly. This field cannot be changed after a `SubscriptionPhase` is created.\n", "readOnly": false, "required": true }, { "name": "periods", "type": "integer", "description": "The number of `cadence`s the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after a `SubscriptionPhase` is created.", "readOnly": false, "required": false }, { "name": "recurring_price_money", "type": "#/components/schemas/Money", "description": "The amount to bill for each `cadence`. Failure to specify this field results in a `MISSING_REQUIRED_PARAMETER` error at runtime.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a `SubscriptionPhase` is created.", "readOnly": false, "required": false }, { "name": "pricing", "type": "#/components/schemas/SubscriptionPricing", "description": "The subscription pricing.", "readOnly": false, "required": false } ] }, { "name": "SubscriptionCadence", "properties": [] }, { "name": "SubscriptionPricing", "properties": [ { "name": "type", "type": "#/components/schemas/SubscriptionPricingType", "description": "RELATIVE or STATIC\n", "readOnly": false, "required": false }, { "name": "discount_ids", "type": "array", "description": "The ids of the discount catalog objects", "readOnly": false, "required": false }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The price of the subscription, if STATIC", "readOnly": false, "required": false } ] }, { "name": "SubscriptionPricingType", "properties": [] }, { "name": "CatalogItemOption", "properties": [ { "name": "name", "type": "string", "description": "The item option's display name for the seller. Must be unique across\nall item options. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "display_name", "type": "string", "description": "The item option's display name for the customer. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The item option's human-readable description. Displayed in the Square\nPoint of Sale app for the seller and in the Online Store or on receipts for\nthe buyer. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "show_colors", "type": "boolean", "description": "If true, display colors for entries in `values` when present.", "readOnly": false, "required": false }, { "name": "values", "type": "array", "description": "A list of CatalogObjects containing the\n`CatalogItemOptionValue`s for this item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObject" } ] }, { "name": "CatalogItemOptionValue", "properties": [ { "name": "item_option_id", "type": "string", "description": "Unique ID of the associated item option.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "Name of this item option value. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "A human-readable description for the option value. This is a searchable attribute for use in applicable query filters.", "readOnly": false, "required": false }, { "name": "color", "type": "string", "description": "The HTML-supported hex color for the item option (e.g., \"#ff8d4e85\").\nOnly displayed if `show_colors` is enabled on the parent `ItemOption`. When\nleft unset, `color` defaults to white (\"#ffffff\") when `show_colors` is\nenabled on the parent `ItemOption`.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "Determines where this option value appears in a list of option values.", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinition", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogCustomAttributeDefinitionType", "description": "The type of this custom attribute. Cannot be modified after creation.\nRequired.\n", "readOnly": false, "required": true }, { "name": "name", "type": "string", "description": " The name of this definition for API and seller-facing UI purposes.\nThe name must be unique within the (merchant, application) pair. Required.\nMay not be empty and may not exceed 255 characters. Can be modified after creation.", "readOnly": false, "required": true }, { "name": "description", "type": "string", "description": "Seller-oriented description of the meaning of this Custom Attribute,\nany constraints that the seller should observe, etc. May be displayed as a tooltip in Square UIs.", "readOnly": false, "required": false }, { "name": "source_application", "type": "#/components/schemas/SourceApplication", "description": "__Read only.__ Contains information about the application that\ncreated this custom attribute definition.", "readOnly": false, "required": false }, { "name": "allowed_object_types", "type": "array", "description": "The set of `CatalogObject` types that this custom atttribute may be applied to.\nCurrently, only `ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, and `CATEGORY` are allowed. At least one type must be included.\n", "readOnly": false, "required": true, "arrayType": "#/components/schemas/CatalogObjectType" }, { "name": "seller_visibility", "type": "#/components/schemas/CatalogCustomAttributeDefinitionSellerVisibility", "description": "The visibility of a custom attribute in seller-facing UIs (including Square Point\nof Sale applications and Square Dashboard). May be modified.\n", "readOnly": false, "required": false }, { "name": "app_visibility", "type": "#/components/schemas/CatalogCustomAttributeDefinitionAppVisibility", "description": "The visibility of a custom attribute to applications other than the application\nthat created the attribute.\n", "readOnly": false, "required": false }, { "name": "string_config", "type": "#/components/schemas/CatalogCustomAttributeDefinitionStringConfig", "description": "Optionally, populated when `type` = `STRING`, unset otherwise.", "readOnly": false, "required": false }, { "name": "number_config", "type": "#/components/schemas/CatalogCustomAttributeDefinitionNumberConfig", "description": "Optionally, populated when `type` = `NUMBER`, unset otherwise.", "readOnly": false, "required": false }, { "name": "selection_config", "type": "#/components/schemas/CatalogCustomAttributeDefinitionSelectionConfig", "description": "Populated when `type` is set to `SELECTION`, unset otherwise.", "readOnly": false, "required": false }, { "name": "custom_attribute_usage_count", "type": "integer", "description": "The number of custom attributes that reference this\ncustom attribute definition. Set by the server in response to a ListCatalog\nrequest with `include_counts` set to `true`. If the actual count is greater\nthan 100, `custom_attribute_usage_count` will be set to `100`.", "readOnly": true, "required": false }, { "name": "key", "type": "string", "description": "The name of the desired custom attribute key that can be used to access\nthe custom attribute value on catalog objects. Cannot be modified after the\ncustom attribute definition has been created.\nMust be between 1 and 60 characters, and may only contain the characters `[a-zA-Z0-9_-]`.", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinitionType", "properties": [] }, { "name": "SourceApplication", "properties": [ { "name": "product", "type": "#/components/schemas/Product", "description": "__Read only__ The [product](entity:Product) type of the application.\n", "readOnly": false, "required": false }, { "name": "application_id", "type": "string", "description": "__Read only__ The Square-assigned ID of the application. This field is used only if the\n[product](entity:Product) type is `EXTERNAL_API`.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "__Read only__ The display name of the application\n(for example, `\"Custom Application\"` or `\"Square POS 4.74 for Android\"`).", "readOnly": false, "required": false } ] }, { "name": "Product", "properties": [] }, { "name": "CatalogCustomAttributeDefinitionSellerVisibility", "properties": [] }, { "name": "CatalogCustomAttributeDefinitionAppVisibility", "properties": [] }, { "name": "CatalogCustomAttributeDefinitionStringConfig", "properties": [ { "name": "enforce_uniqueness", "type": "boolean", "description": "If true, each Custom Attribute instance associated with this Custom Attribute\nDefinition must have a unique value within the seller's catalog. For\nexample, this may be used for a value like a SKU that should not be\nduplicated within a seller's catalog. May not be modified after the\ndefinition has been created.", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinitionNumberConfig", "properties": [ { "name": "precision", "type": "integer", "description": "An integer between 0 and 5 that represents the maximum number of\npositions allowed after the decimal in number custom attribute values\nFor example:\n\n- if the precision is 0, the quantity can be 1, 2, 3, etc.\n- if the precision is 1, the quantity can be 0.1, 0.2, etc.\n- if the precision is 2, the quantity can be 0.01, 0.12, etc.\n\nDefault: 5", "readOnly": false, "required": false } ] }, { "name": "CatalogCustomAttributeDefinitionSelectionConfig", "properties": [ { "name": "max_allowed_selections", "type": "integer", "description": "The maximum number of selections that can be set. The maximum value for this\nattribute is 100. The default value is 1. The value can be modified, but changing the value will not\naffect existing custom attribute values on objects. Clients need to\nhandle custom attributes with more selected values than allowed by this limit.", "readOnly": false, "required": false }, { "name": "allowed_selections", "type": "array", "description": "The set of valid `CatalogCustomAttributeSelections`. Up to a maximum of 100\nselections can be defined. Can be modified.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection" } ] }, { "name": "CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection", "properties": [ { "name": "uid", "type": "string", "description": "Unique ID set by Square.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "Selection name, unique within `allowed_selections`.", "readOnly": false, "required": true } ] }, { "name": "CatalogQuickAmountsSettings", "properties": [ { "name": "option", "type": "#/components/schemas/CatalogQuickAmountsSettingsOption", "description": "Represents the option seller currently uses on Quick Amounts.\n", "readOnly": false, "required": true }, { "name": "eligible_for_auto_amounts", "type": "boolean", "description": "Represents location's eligibility for auto amounts\nThe boolean should be consistent with whether there are AUTO amounts in the `amounts`.", "readOnly": false, "required": false }, { "name": "amounts", "type": "array", "description": "Represents a set of Quick Amounts at this location.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogQuickAmount" } ] }, { "name": "CatalogQuickAmountsSettingsOption", "properties": [] }, { "name": "CatalogQuickAmount", "properties": [ { "name": "type", "type": "#/components/schemas/CatalogQuickAmountType", "description": "Represents the type of the Quick Amount.\n", "readOnly": false, "required": true }, { "name": "amount", "type": "#/components/schemas/Money", "description": "Represents the actual amount of the Quick Amount with Money type.", "readOnly": false, "required": true }, { "name": "score", "type": "integer", "description": "Describes the ranking of the Quick Amount provided by machine learning model, in the range [0, 100].\nMANUAL type amount will always have score = 100.", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The order in which this Quick Amount should be displayed.", "readOnly": false, "required": false } ] }, { "name": "CatalogQuickAmountType", "properties": [] }, { "name": "CatalogSubscriptionPlanVariation", "properties": [ { "name": "name", "type": "string", "description": "The name of the plan variation.", "readOnly": false, "required": true }, { "name": "phases", "type": "array", "description": "A list containing each [SubscriptionPhase](entity:SubscriptionPhase) for this plan variation.", "readOnly": false, "required": true, "arrayType": "#/components/schemas/SubscriptionPhase" }, { "name": "subscription_plan_id", "type": "string", "description": "The id of the subscription plan, if there is one.", "readOnly": false, "required": false }, { "name": "monthly_billing_anchor_date", "type": "integer", "description": "The day of the month the billing period starts.", "readOnly": false, "required": false }, { "name": "can_prorate", "type": "boolean", "description": "Whether bills for this plan variation can be split for proration.", "readOnly": false, "required": false }, { "name": "successor_plan_variation_id", "type": "string", "description": "The ID of a \"successor\" plan variation to this one. If the field is set, and this object is disabled at all\nlocations, it indicates that this variation is deprecated and the object identified by the successor ID be used in\nits stead.", "readOnly": false, "required": false } ] }, { "name": "CatalogAvailabilityPeriod", "properties": [ { "name": "start_local_time", "type": "string", "description": "The start time of an availability period, specified in local time using partial-time\nRFC 3339 format. For example, `8:30:00` for a period starting at 8:30 in the morning.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC.", "readOnly": false, "required": false }, { "name": "end_local_time", "type": "string", "description": "The end time of an availability period, specified in local time using partial-time\nRFC 3339 format. For example, `21:00:00` for a period ending at 9:00 in the evening.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC.", "readOnly": false, "required": false }, { "name": "day_of_week", "type": "#/components/schemas/DayOfWeek", "description": "The day of the week for this availability period.\n", "readOnly": false, "required": false } ] }, { "name": "DayOfWeek", "properties": [] } ], "DeleteCatalogObjectRequest": [ { "name": "DeleteCatalogObjectRequest", "properties": [ { "name": "object_id", "type": "string", "description": "The ID of the catalog object to be deleted. When an object is deleted, other\nobjects in the graph that depend on that object will be deleted as well (for example, deleting a\ncatalog item will delete its catalog item variations).", "readOnly": false, "required": true } ] } ], "RetrieveCatalogObjectRequest": [ { "name": "RetrieveCatalogObjectRequest", "properties": [ { "name": "include_related_objects", "type": "boolean", "description": "If `true`, the response will include additional objects that are related to the\nrequested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field\nof the response. These objects are put in the `related_objects` field. Setting this to `true` is\nhelpful when the objects are needed for immediate display to a user.\nThis process only goes one level deep. Objects referenced by the related objects will not be included. For example,\n\nif the `objects` field of the response contains a CatalogItem, its associated\nCatalogCategory objects, CatalogTax objects, CatalogImage objects and\nCatalogModifierLists will be returned in the `related_objects` field of the\nresponse. If the `objects` field of the response contains a CatalogItemVariation,\nits parent CatalogItem will be returned in the `related_objects` field of\nthe response.\n\nDefault value: `false`", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "Requests objects as of a specific version of the catalog. This allows you to retrieve historical\nversions of objects. The value to retrieve a specific version of an object can be found\nin the version field of [CatalogObject](entity:CatalogObject)s. If not included, results will\nbe from the current version of the catalog.", "readOnly": false, "required": false }, { "name": "include_category_path_to_root", "type": "boolean", "description": "Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists\nof `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category\nand ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned\nin the response payload.", "readOnly": false, "required": false }, { "name": "object_id", "type": "string", "description": "The object ID of any type of catalog objects to be retrieved.", "readOnly": false, "required": true } ] } ], "SearchCatalogObjectsRequest": [ { "name": "SearchCatalogObjectsRequest", "properties": [ { "name": "cursor", "type": "string", "description": "The pagination cursor returned in the previous response. Leave unset for an initial request.\nSee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.", "readOnly": false, "required": false }, { "name": "object_types", "type": "array", "description": "The desired set of object types to appear in the search results.\n\nIf this is unspecified, the operation returns objects of all the top level types at the version\nof the Square API used to make the request. Object types that are nested onto other object types\nare not included in the defaults.\n\nAt the current API version the default object types are:\nITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, \nPRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,\nSUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS.\n\nNote that if you wish for the query to return objects belonging to nested types (i.e., COMPONENT, IMAGE,\nITEM_OPTION_VAL, ITEM_VARIATION, or MODIFIER), you must explicitly include all the types of interest\nin this field.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogObjectType" }, { "name": "include_deleted_objects", "type": "boolean", "description": "If `true`, deleted objects will be included in the results. Defaults to `false`. Deleted objects will have their `is_deleted` field set to `true`. If `include_deleted_objects` is `true`, then the `include_category_path_to_root` request parameter must be `false`. Both properties cannot be `true` at the same time.", "readOnly": false, "required": false }, { "name": "include_related_objects", "type": "boolean", "description": "If `true`, the response will include additional objects that are related to the\nrequested objects. Related objects are objects that are referenced by object ID by the objects\nin the response. This is helpful if the objects are being fetched for immediate display to a user.\nThis process only goes one level deep. Objects referenced by the related objects will not be included.\nFor example:\n\nIf the `objects` field of the response contains a CatalogItem, its associated\nCatalogCategory objects, CatalogTax objects, CatalogImage objects and\nCatalogModifierLists will be returned in the `related_objects` field of the\nresponse. If the `objects` field of the response contains a CatalogItemVariation,\nits parent CatalogItem will be returned in the `related_objects` field of\nthe response.\n\nDefault value: `false`", "readOnly": false, "required": false }, { "name": "begin_time", "type": "string", "description": "Return objects modified after this [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates), in RFC 3339\nformat, e.g., `2016-09-04T23:59:33.123Z`. The timestamp is exclusive - objects with a\ntimestamp equal to `begin_time` will not be included in the response.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "query", "type": "#/components/schemas/CatalogQuery", "description": "A query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "A limit on the number of results to be returned in a single page. The limit is advisory -\nthe implementation may return more or fewer results. If the supplied limit is negative, zero, or\nis higher than the maximum limit of 1,000, it will be ignored.", "readOnly": false, "required": false }, { "name": "include_category_path_to_root", "type": "boolean", "description": "Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists of `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned in the response payload. If `include_category_path_to_root` is `true`, then the `include_deleted_objects` request parameter must be `false`. Both properties cannot be `true` at the same time.", "readOnly": false, "required": false } ] }, { "name": "CatalogObjectType", "properties": [] }, { "name": "CatalogQuery", "properties": [ { "name": "sorted_attribute_query", "type": "#/components/schemas/CatalogQuerySortedAttribute", "description": "A query expression to sort returned query result by the given attribute.", "readOnly": false, "required": false }, { "name": "exact_query", "type": "#/components/schemas/CatalogQueryExact", "description": "An exact query expression to return objects with attribute name and value\nmatching the specified attribute name and value exactly. Value matching is case insensitive.", "readOnly": false, "required": false }, { "name": "set_query", "type": "#/components/schemas/CatalogQuerySet", "description": "A set query expression to return objects with attribute name and value\nmatching the specified attribute name and any of the specified attribute values exactly.\nValue matching is case insensitive.", "readOnly": false, "required": false }, { "name": "prefix_query", "type": "#/components/schemas/CatalogQueryPrefix", "description": "A prefix query expression to return objects with attribute values\nthat have a prefix matching the specified string value. Value matching is case insensitive.", "readOnly": false, "required": false }, { "name": "range_query", "type": "#/components/schemas/CatalogQueryRange", "description": "A range query expression to return objects with numeric values\nthat lie in the specified range.", "readOnly": false, "required": false }, { "name": "text_query", "type": "#/components/schemas/CatalogQueryText", "description": "A text query expression to return objects whose searchable attributes contain all of the given\nkeywords, irrespective of their order. For example, if a `CatalogItem` contains custom attribute values of\n`{\"name\": \"t-shirt\"}` and `{\"description\": \"Small, Purple\"}`, the query filter of `{\"keywords\": [\"shirt\", \"sma\", \"purp\"]}`\nreturns this item.", "readOnly": false, "required": false }, { "name": "items_for_tax_query", "type": "#/components/schemas/CatalogQueryItemsForTax", "description": "A query expression to return items that have any of the specified taxes (as identified by the corresponding `CatalogTax` object IDs) enabled.", "readOnly": false, "required": false }, { "name": "items_for_modifier_list_query", "type": "#/components/schemas/CatalogQueryItemsForModifierList", "description": "A query expression to return items that have any of the given modifier list (as identified by the corresponding `CatalogModifierList`s IDs) enabled.", "readOnly": false, "required": false }, { "name": "items_for_item_options_query", "type": "#/components/schemas/CatalogQueryItemsForItemOptions", "description": "A query expression to return items that contains the specified item options (as identified the corresponding `CatalogItemOption` IDs).", "readOnly": false, "required": false }, { "name": "item_variations_for_item_option_values_query", "type": "#/components/schemas/CatalogQueryItemVariationsForItemOptionValues", "description": "A query expression to return item variations (of the [CatalogItemVariation](entity:CatalogItemVariation) type) that\ncontain all of the specified `CatalogItemOption` IDs.", "readOnly": false, "required": false } ] }, { "name": "CatalogQuerySortedAttribute", "properties": [ { "name": "attribute_name", "type": "string", "description": "The attribute whose value is used as the sort key.", "readOnly": false, "required": true }, { "name": "initial_attribute_value", "type": "string", "description": "The first attribute value to be returned by the query. Ascending sorts will return only\nobjects with this value or greater, while descending sorts will return only objects with this value\nor less. If unset, start at the beginning (for ascending sorts) or end (for descending sorts).", "readOnly": false, "required": false }, { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "The desired sort order, `\"ASC\"` (ascending) or `\"DESC\"` (descending).\n", "readOnly": false, "required": false } ] }, { "name": "SortOrder", "properties": [] }, { "name": "CatalogQueryExact", "properties": [ { "name": "attribute_name", "type": "string", "description": "The name of the attribute to be searched. Matching of the attribute name is exact.", "readOnly": false, "required": true }, { "name": "attribute_value", "type": "string", "description": "The desired value of the search attribute. Matching of the attribute value is case insensitive and can be partial.\nFor example, if a specified value of \"sma\", objects with the named attribute value of \"Small\", \"small\" are both matched.", "readOnly": false, "required": true } ] }, { "name": "CatalogQuerySet", "properties": [ { "name": "attribute_name", "type": "string", "description": "The name of the attribute to be searched. Matching of the attribute name is exact.", "readOnly": false, "required": true }, { "name": "attribute_values", "type": "array", "description": "The desired values of the search attribute. Matching of the attribute values is exact and case insensitive.\nA maximum of 250 values may be searched in a request.", "readOnly": false, "required": true } ] }, { "name": "CatalogQueryPrefix", "properties": [ { "name": "attribute_name", "type": "string", "description": "The name of the attribute to be searched.", "readOnly": false, "required": true }, { "name": "attribute_prefix", "type": "string", "description": "The desired prefix of the search attribute value.", "readOnly": false, "required": true } ] }, { "name": "CatalogQueryRange", "properties": [ { "name": "attribute_name", "type": "string", "description": "The name of the attribute to be searched.", "readOnly": false, "required": true }, { "name": "attribute_min_value", "type": "integer", "description": "The desired minimum value for the search attribute (inclusive).", "readOnly": false, "required": false }, { "name": "attribute_max_value", "type": "integer", "description": "The desired maximum value for the search attribute (inclusive).", "readOnly": false, "required": false } ] }, { "name": "CatalogQueryText", "properties": [ { "name": "keywords", "type": "array", "description": "A list of 1, 2, or 3 search keywords. Keywords with fewer than 3 alphanumeric characters are ignored.", "readOnly": false, "required": true } ] }, { "name": "CatalogQueryItemsForTax", "properties": [ { "name": "tax_ids", "type": "array", "description": "A set of `CatalogTax` IDs to be used to find associated `CatalogItem`s.", "readOnly": false, "required": true } ] }, { "name": "CatalogQueryItemsForModifierList", "properties": [ { "name": "modifier_list_ids", "type": "array", "description": "A set of `CatalogModifierList` IDs to be used to find associated `CatalogItem`s.", "readOnly": false, "required": true } ] }, { "name": "CatalogQueryItemsForItemOptions", "properties": [ { "name": "item_option_ids", "type": "array", "description": "A set of `CatalogItemOption` IDs to be used to find associated\n`CatalogItem`s. All Items that contain all of the given Item Options (in any order)\nwill be returned.", "readOnly": false, "required": false } ] }, { "name": "CatalogQueryItemVariationsForItemOptionValues", "properties": [ { "name": "item_option_value_ids", "type": "array", "description": "A set of `CatalogItemOptionValue` IDs to be used to find associated\n`CatalogItemVariation`s. All ItemVariations that contain all of the given\nItem Option Values (in any order) will be returned.", "readOnly": false, "required": false } ] } ], "SearchCatalogItemsRequest": [ { "name": "SearchCatalogItemsRequest", "properties": [ { "name": "text_filter", "type": "string", "description": "The text filter expression to return items or item variations containing specified text in\nthe `name`, `description`, or `abbreviation` attribute value of an item, or in\nthe `name`, `sku`, or `upc` attribute value of an item variation.", "readOnly": false, "required": false }, { "name": "category_ids", "type": "array", "description": "The category id query expression to return items containing the specified category IDs.", "readOnly": false, "required": false }, { "name": "stock_levels", "type": "array", "description": "The stock-level query expression to return item variations with the specified stock levels.\n", "readOnly": false, "required": false, "arrayType": "#/components/schemas/SearchCatalogItemsRequestStockLevel" }, { "name": "enabled_location_ids", "type": "array", "description": "The enabled-location query expression to return items and item variations having specified enabled locations.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The pagination token, returned in the previous response, used to fetch the next batch of pending results.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return per page. The default value is 100.", "readOnly": false, "required": false }, { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "The order to sort the results by item names. The default sort order is ascending (`ASC`).\n", "readOnly": false, "required": false }, { "name": "product_types", "type": "array", "description": "The product types query expression to return items or item variations having the specified product types.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CatalogItemProductType" }, { "name": "custom_attribute_filters", "type": "array", "description": "The customer-attribute filter to return items or item variations matching the specified\ncustom attribute expressions. A maximum number of 10 custom attribute expressions are supported in\na single call to the [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CustomAttributeFilter" }, { "name": "archived_state", "type": "#/components/schemas/ArchivedState", "description": "The query filter to return not archived (`ARCHIVED_STATE_NOT_ARCHIVED`), archived (`ARCHIVED_STATE_ARCHIVED`), or either type (`ARCHIVED_STATE_ALL`) of items.", "readOnly": false, "required": false } ] }, { "name": "SearchCatalogItemsRequestStockLevel", "properties": [] }, { "name": "SortOrder", "properties": [] }, { "name": "CatalogItemProductType", "properties": [] }, { "name": "CustomAttributeFilter", "properties": [ { "name": "custom_attribute_definition_id", "type": "string", "description": "A query expression to filter items or item variations by matching their custom attributes'\n`custom_attribute_definition_id` property value against the the specified id.\nExactly one of `custom_attribute_definition_id` or `key` must be specified.", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "A query expression to filter items or item variations by matching their custom attributes'\n`key` property value against the specified key.\nExactly one of `custom_attribute_definition_id` or `key` must be specified.", "readOnly": false, "required": false }, { "name": "string_filter", "type": "string", "description": "A query expression to filter items or item variations by matching their custom attributes'\n`string_value` property value against the specified text.\nExactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified.", "readOnly": false, "required": false }, { "name": "number_filter", "type": "#/components/schemas/Range", "description": "A query expression to filter items or item variations with their custom attributes\ncontaining a number value within the specified range.\nExactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified.", "readOnly": false, "required": false }, { "name": "selection_uids_filter", "type": "array", "description": "A query expression to filter items or item variations by matching their custom attributes'\n`selection_uid_values` values against the specified selection uids.\nExactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified.", "readOnly": false, "required": false }, { "name": "bool_filter", "type": "boolean", "description": "A query expression to filter items or item variations by matching their custom attributes'\n`boolean_value` property values against the specified Boolean expression.\nExactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified.", "readOnly": false, "required": false } ] }, { "name": "Range", "properties": [ { "name": "min", "type": "string", "description": "The lower bound of the number range. At least one of `min` or `max` must be specified.\nIf unspecified, the results will have no minimum value.", "readOnly": false, "required": false }, { "name": "max", "type": "string", "description": "The upper bound of the number range. At least one of `min` or `max` must be specified.\nIf unspecified, the results will have no maximum value.", "readOnly": false, "required": false } ] }, { "name": "ArchivedState", "properties": [] } ], "UpdateItemModifierListsRequest": [ { "name": "UpdateItemModifierListsRequest", "properties": [ { "name": "item_ids", "type": "array", "description": "The IDs of the catalog items associated with the CatalogModifierList objects being updated.", "readOnly": false, "required": true }, { "name": "modifier_lists_to_enable", "type": "array", "description": "The IDs of the CatalogModifierList objects to enable for the CatalogItem.\nAt least one of `modifier_lists_to_enable` or `modifier_lists_to_disable` must be specified.", "readOnly": false, "required": false }, { "name": "modifier_lists_to_disable", "type": "array", "description": "The IDs of the CatalogModifierList objects to disable for the CatalogItem.\nAt least one of `modifier_lists_to_enable` or `modifier_lists_to_disable` must be specified.", "readOnly": false, "required": false } ] } ], "UpdateItemTaxesRequest": [ { "name": "UpdateItemTaxesRequest", "properties": [ { "name": "item_ids", "type": "array", "description": "IDs for the CatalogItems associated with the CatalogTax objects being updated.\nNo more than 1,000 IDs may be provided.", "readOnly": false, "required": true }, { "name": "taxes_to_enable", "type": "array", "description": "IDs of the CatalogTax objects to enable.\nAt least one of `taxes_to_enable` or `taxes_to_disable` must be specified.", "readOnly": false, "required": false }, { "name": "taxes_to_disable", "type": "array", "description": "IDs of the CatalogTax objects to disable.\nAt least one of `taxes_to_enable` or `taxes_to_disable` must be specified.", "readOnly": false, "required": false } ] } ], "RetrieveLocationSettingsRequest": [ { "name": "RetrieveLocationSettingsRequest", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the location for which to retrieve settings.", "readOnly": false, "required": true } ] } ], "UpdateLocationSettingsRequest": [ { "name": "UpdateLocationSettingsRequest", "properties": [ { "name": "location_settings", "type": "#/components/schemas/CheckoutLocationSettings", "description": "Describe your updates using the `location_settings` object. Make sure it contains only the fields that have changed.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The ID of the location for which to retrieve settings.", "readOnly": false, "required": true } ] }, { "name": "CheckoutLocationSettings", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the location that these settings apply to.", "readOnly": false, "required": false }, { "name": "customer_notes_enabled", "type": "boolean", "description": "Indicates whether customers are allowed to leave notes at checkout.", "readOnly": false, "required": false }, { "name": "policies", "type": "array", "description": "Policy information is displayed at the bottom of the checkout pages.\nYou can set a maximum of two policies.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CheckoutLocationSettingsPolicy" }, { "name": "branding", "type": "#/components/schemas/CheckoutLocationSettingsBranding", "description": "The branding settings for this location.", "readOnly": false, "required": false }, { "name": "tipping", "type": "#/components/schemas/CheckoutLocationSettingsTipping", "description": "The tip settings for this location.", "readOnly": false, "required": false }, { "name": "coupons", "type": "#/components/schemas/CheckoutLocationSettingsCoupons", "description": "The coupon settings for this location.", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the settings were last updated, in RFC 3339 format.\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\nUTC: 2020-01-26T02:25:34Z\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CheckoutLocationSettingsPolicy", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID to identify the policy when making changes. You must set the UID for policy updates, but it’s optional when setting new policies.", "readOnly": false, "required": false }, { "name": "title", "type": "string", "description": "The title of the policy. This is required when setting the description, though you can update it in a different request.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The description of the policy.", "readOnly": false, "required": false } ] }, { "name": "CheckoutLocationSettingsBranding", "properties": [ { "name": "header_type", "type": "#/components/schemas/CheckoutLocationSettingsBrandingHeaderType", "description": "Show the location logo on the checkout page.\n", "readOnly": false, "required": false }, { "name": "button_color", "type": "string", "description": "The HTML-supported hex color for the button on the checkout page (for example, \"#FFFFFF\").", "readOnly": false, "required": false }, { "name": "button_shape", "type": "#/components/schemas/CheckoutLocationSettingsBrandingButtonShape", "description": "The shape of the button on the checkout page.\n", "readOnly": false, "required": false } ] }, { "name": "CheckoutLocationSettingsBrandingHeaderType", "properties": [] }, { "name": "CheckoutLocationSettingsBrandingButtonShape", "properties": [] }, { "name": "CheckoutLocationSettingsTipping", "properties": [ { "name": "percentages", "type": "array", "description": "Set three custom percentage amounts that buyers can select at checkout. If Smart Tip is enabled, this only applies to transactions totaling $10 or more.", "readOnly": false, "required": false }, { "name": "smart_tipping_enabled", "type": "boolean", "description": "Enables Smart Tip Amounts. If Smart Tip Amounts is enabled, tipping works as follows:\nIf a transaction is less than $10, the available tipping options include No Tip, $1, $2, or $3.\nIf a transaction is $10 or more, the available tipping options include No Tip, 15%, 20%, or 25%. \nYou can set custom percentage amounts with the `percentages` field.", "readOnly": false, "required": false }, { "name": "default_percent", "type": "integer", "description": "Set the pre-selected percentage amounts that appear at checkout. If Smart Tip is enabled, this only applies to transactions totaling $10 or more.", "readOnly": false, "required": false }, { "name": "smart_tips", "type": "array", "description": "Show the Smart Tip Amounts for this location.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Money" }, { "name": "default_smart_tip", "type": "#/components/schemas/Money", "description": "Set the pre-selected whole amount that appears at checkout when Smart Tip is enabled and the transaction amount is less than $10.", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "CheckoutLocationSettingsCoupons", "properties": [ { "name": "enabled", "type": "boolean", "description": "Indicates whether coupons are enabled for this location.", "readOnly": false, "required": false } ] } ], "RetrieveMerchantSettingsRequest": [ { "name": "RetrieveMerchantSettingsRequest", "properties": [] } ], "UpdateMerchantSettingsRequest": [ { "name": "UpdateMerchantSettingsRequest", "properties": [ { "name": "merchant_settings", "type": "#/components/schemas/CheckoutMerchantSettings", "description": "Describe your updates using the `merchant_settings` object. Make sure it contains only the fields that have changed.", "readOnly": false, "required": true } ] }, { "name": "CheckoutMerchantSettings", "properties": [ { "name": "payment_methods", "type": "#/components/schemas/CheckoutMerchantSettingsPaymentMethods", "description": "The set of payment methods accepted for the merchant's account.", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the settings were last updated, in RFC 3339 format.\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\nUTC: 2020-01-26T02:25:34Z\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CheckoutMerchantSettingsPaymentMethods", "properties": [ { "name": "apple_pay", "type": "#/components/schemas/CheckoutMerchantSettingsPaymentMethodsPaymentMethod", "description": "Property apple_pay of CheckoutMerchantSettingsPaymentMethods", "readOnly": false, "required": false }, { "name": "google_pay", "type": "#/components/schemas/CheckoutMerchantSettingsPaymentMethodsPaymentMethod", "description": "Property google_pay of CheckoutMerchantSettingsPaymentMethods", "readOnly": false, "required": false }, { "name": "cash_app", "type": "#/components/schemas/CheckoutMerchantSettingsPaymentMethodsPaymentMethod", "description": "Property cash_app of CheckoutMerchantSettingsPaymentMethods", "readOnly": false, "required": false }, { "name": "afterpay_clearpay", "type": "#/components/schemas/CheckoutMerchantSettingsPaymentMethodsAfterpayClearpay", "description": "Property afterpay_clearpay of CheckoutMerchantSettingsPaymentMethods", "readOnly": false, "required": false } ] }, { "name": "CheckoutMerchantSettingsPaymentMethodsPaymentMethod", "properties": [ { "name": "enabled", "type": "boolean", "description": "Indicates whether the payment method is enabled for the account.", "readOnly": false, "required": false } ] }, { "name": "CheckoutMerchantSettingsPaymentMethodsAfterpayClearpay", "properties": [ { "name": "order_eligibility_range", "type": "#/components/schemas/CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange", "description": "Afterpay is shown as an option for order totals falling within the configured range.", "readOnly": false, "required": false }, { "name": "item_eligibility_range", "type": "#/components/schemas/CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange", "description": "Afterpay is shown as an option for item totals falling within the configured range.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "Indicates whether the payment method is enabled for the account.", "readOnly": true, "required": false } ] }, { "name": "CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange", "properties": [ { "name": "min", "type": "#/components/schemas/Money", "description": "Property min of CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange", "readOnly": false, "required": true }, { "name": "max", "type": "#/components/schemas/Money", "description": "Property max of CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange", "readOnly": false, "required": true } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] } ], "ListPaymentLinksRequest": [ { "name": "ListPaymentLinksRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\nIf a cursor is not provided, the endpoint returns the first page of the results.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "A limit on the number of results to return per page. The limit is advisory and\nthe implementation might return more or less results. If the supplied limit is negative, zero, or\ngreater than the maximum limit of 1000, it is ignored.\n\nDefault value: `100`", "readOnly": false, "required": false } ] } ], "CreatePaymentLinkRequest": [ { "name": "CreatePaymentLinkRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `CreatePaymentLinkRequest` request.\nIf you do not provide a unique string (or provide an empty string as the value),\nthe endpoint treats each request as independent.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "A description of the payment link. You provide this optional description that is useful in your\napplication context. It is not used anywhere.", "readOnly": false, "required": false }, { "name": "quick_pay", "type": "#/components/schemas/QuickPay", "description": "Describes an ad hoc item and price for which to generate a quick pay checkout link.\nFor more information,\nsee [Quick Pay Checkout](https://developer.squareup.com/docs/checkout-api/quick-pay-checkout).", "readOnly": false, "required": false }, { "name": "order", "type": "#/components/schemas/Order", "description": "Describes the `Order` for which to create a checkout link.\nFor more information,\nsee [Square Order Checkout](https://developer.squareup.com/docs/checkout-api/square-order-checkout).", "readOnly": false, "required": false }, { "name": "checkout_options", "type": "#/components/schemas/CheckoutOptions", "description": "Describes optional fields to add to the resulting checkout page.\nFor more information,\nsee [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations).", "readOnly": false, "required": false }, { "name": "pre_populated_data", "type": "#/components/schemas/PrePopulatedData", "description": "Describes fields to prepopulate in the resulting checkout page.\nFor more information, see [Prepopulate the shipping address](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations#prepopulate-the-shipping-address).", "readOnly": false, "required": false }, { "name": "payment_note", "type": "string", "description": "A note for the payment. After processing the payment, Square adds this note to the resulting `Payment`.", "readOnly": false, "required": false } ] }, { "name": "QuickPay", "properties": [ { "name": "name", "type": "string", "description": "The ad hoc item name. In the resulting `Order`, this name appears as the line item name.", "readOnly": false, "required": true }, { "name": "price_money", "type": "#/components/schemas/Money", "description": "The price of the item.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The ID of the business location the checkout is associated with.", "readOnly": false, "required": true } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "Order", "properties": [ { "name": "id", "type": "string", "description": "The order's unique ID.", "readOnly": true, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the seller location that this order is associated with.", "readOnly": false, "required": true }, { "name": "reference_id", "type": "string", "description": "A client-specified ID to associate an entity in another system\nwith this order.", "readOnly": false, "required": false }, { "name": "source", "type": "#/components/schemas/OrderSource", "description": "The origination details of the order.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the [customer](entity:Customer) associated with the order.\n\nYou should specify a `customer_id` on the order (or the payment) to ensure that transactions\nare reliably linked to customers. Omitting this field might result in the creation of new\n[instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles).", "readOnly": false, "required": false }, { "name": "line_items", "type": "array", "description": "The line items included in the order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItem" }, { "name": "taxes", "type": "array", "description": "The list of all taxes associated with the order.\n\nTaxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an\n`OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes\nwith `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item.\n\nOn reads, each tax in the list includes the total amount of that tax applied to the order.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated\n`line_items.taxes` field results in an error. Use `line_items.applied_taxes`\ninstead.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemTax" }, { "name": "discounts", "type": "array", "description": "The list of all discounts associated with the order.\n\nDiscounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`,\nan `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to.\nFor discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount`\nfor every line item.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated\n`line_items.discounts` field results in an error. Use `line_items.applied_discounts`\ninstead.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemDiscount" }, { "name": "service_charges", "type": "array", "description": "A list of service charges applied to the order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderServiceCharge" }, { "name": "fulfillments", "type": "array", "description": "Details about order fulfillment.\n\nOrders can only be created with at most one fulfillment. However, orders returned\nby the API might contain multiple fulfillments.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Fulfillment" }, { "name": "returns", "type": "array", "description": "A collection of items from sale orders being returned in this one. Normally part of an\nitemized return or exchange. There is exactly one `Return` object per sale `Order` being\nreferenced.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturn" }, { "name": "return_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "The rollup of the returned money amounts.", "readOnly": true, "required": false }, { "name": "net_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "The net money amounts (sale money - return money).", "readOnly": true, "required": false }, { "name": "rounding_adjustment", "type": "#/components/schemas/OrderRoundingAdjustment", "description": "A positive rounding adjustment to the total of the order. This adjustment is commonly\nused to apply cash rounding when the minimum unit of account is smaller than the lowest physical\ndenomination of the currency.", "readOnly": true, "required": false }, { "name": "tenders", "type": "array", "description": "The tenders that were used to pay for the order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/Tender" }, { "name": "refunds", "type": "array", "description": "The refunds that are part of this order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/Refund" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp for when the order was created, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "closed_at", "type": "string", "description": "The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "state", "type": "#/components/schemas/OrderState", "description": "The current state of the order.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The version number, which is incremented each time an update is committed to the order.\nOrders not created through the API do not include a version number and\ntherefore cannot be updated.\n\n[Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders).", "readOnly": false, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_tip_money", "type": "#/components/schemas/Money", "description": "The total amount of tip money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of money collected in service charges for the order.\n\nNote: `total_service_charge_money` is the sum of `applied_money` fields for each individual\nservice charge. Therefore, `total_service_charge_money` only includes inclusive tax amounts,\nnot additive tax amounts.", "readOnly": true, "required": false }, { "name": "ticket_name", "type": "string", "description": "A short-term identifier for the order (such as a customer first name,\ntable number, or auto-generated order number that resets daily).", "readOnly": false, "required": false }, { "name": "pricing_options", "type": "#/components/schemas/OrderPricingOptions", "description": "Pricing options for an order. The options affect how the order's price is calculated.\nThey can be used, for example, to apply automatic price adjustments that are based on\npreconfigured [pricing rules](entity:CatalogPricingRule).", "readOnly": false, "required": false }, { "name": "rewards", "type": "array", "description": "A set-like list of Rewards that have been added to the Order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReward" }, { "name": "net_amount_due_money", "type": "#/components/schemas/Money", "description": "The net amount of money due on the order.", "readOnly": true, "required": false } ] }, { "name": "OrderSource", "properties": [ { "name": "name", "type": "string", "description": "The name used to identify the place (physical or digital) that an order originates.\nIf unset, the name defaults to the name of the application that created the order.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItem", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the line item only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the line item.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The count, or measurement, of a line item being purchased:\n\nIf `quantity` is a whole number, and `quantity_unit` is not specified, then `quantity` denotes an item count. For example: `3` apples.\n\nIf `quantity` is a whole or decimal number, and `quantity_unit` is also specified, then `quantity` denotes a measurement. For example: `2.25` pounds of broccoli.\n\nFor more information, see [Specify item quantity and measurement unit](https://developer.squareup.com/docs/orders-api/create-orders#specify-item-quantity-and-measurement-unit).\n\nLine items with a quantity of `0` are automatically removed\nwhen paying for or otherwise completing the order.", "readOnly": false, "required": true }, { "name": "quantity_unit", "type": "#/components/schemas/OrderQuantityUnit", "description": "The measurement unit and decimal precision that this line item's quantity is measured in.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "An optional note associated with the line item.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this line item.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item references.", "readOnly": false, "required": false }, { "name": "variation_name", "type": "string", "description": "The name of the variation applied to this line item.", "readOnly": false, "required": false }, { "name": "item_type", "type": "#/components/schemas/OrderLineItemItemType", "description": "The type of line item: an itemized sale, a non-itemized sale (custom amount), or the\nactivation or reloading of a gift card.\n", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this line item. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "modifiers", "type": "array", "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemModifier" }, { "name": "applied_taxes", "type": "array", "description": "The list of references to taxes applied to this line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a\ntop-level `OrderLineItemTax` applied to the line item. On reads, the\namount applied is populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every line\nitem for all `ORDER` scoped taxes added to the order. `OrderLineItemAppliedTax`\nrecords for `LINE_ITEM` scoped taxes must be added in requests for the tax\nto apply to any line items.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "applied_discounts", "type": "array", "description": "The list of references to discounts applied to this line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderLineItemDiscounts` applied to the line item. On reads, the amount\napplied is populated.\n\nAn `OrderLineItemAppliedDiscount` is automatically created on every line item for all\n`ORDER` scoped discounts that are added to the order. `OrderLineItemAppliedDiscount` records\nfor `LINE_ITEM` scoped discounts must be added in requests for the discount to apply to any\nline items.\n\nTo change the amount of a discount, modify the referenced top-level discount.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedDiscount" }, { "name": "applied_service_charges", "type": "array", "description": "The list of references to service charges applied to this line item. Each\n`OrderLineItemAppliedServiceCharge` has a `service_charge_id` that references the `uid` of a\ntop-level `OrderServiceCharge` applied to the line item. On reads, the amount applied is\npopulated.\n\nTo change the amount of a service charge, modify the referenced top-level service charge.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedServiceCharge" }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for a single unit of the line item.", "readOnly": false, "required": false }, { "name": "variation_total_price_money", "type": "#/components/schemas/Money", "description": "The total price of all item variations sold in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity`.\nIt does not include modifiers.", "readOnly": true, "required": false }, { "name": "gross_sales_money", "type": "#/components/schemas/Money", "description": "The amount of money made in gross sales for this line item.\nThe amount is calculated as the sum of the variation's total price and each modifier's total price.\nFor inclusive tax items in the US, Canada, and Japan, tax is deducted from `gross_sales_money`. For Europe and\nAustralia, inclusive tax remains as part of the gross sale calculation.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the line item.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to collect for the line item.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for this line item.", "readOnly": true, "required": false }, { "name": "pricing_blocklists", "type": "#/components/schemas/OrderLineItemPricingBlocklists", "description": "Describes pricing adjustments that are blocked from automatic\napplication to a line item. For more information, see\n[Apply Taxes and Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).", "readOnly": false, "required": false }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of apportioned service charge money to collect for the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderQuantityUnit", "properties": [ { "name": "measurement_unit", "type": "#/components/schemas/MeasurementUnit", "description": "A [MeasurementUnit](entity:MeasurementUnit) that represents the\nunit of measure for the quantity.", "readOnly": false, "required": false }, { "name": "precision", "type": "integer", "description": "For non-integer quantities, represents the number of digits after the decimal point that are\nrecorded for this quantity.\n\nFor example, a precision of 1 allows quantities such as `\"1.0\"` and `\"1.1\"`, but not `\"1.01\"`.\n\nMin: 0. Max: 5.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing the\n[CatalogMeasurementUnit](entity:CatalogMeasurementUnit).\n\nThis field is set when this is a catalog-backed measurement unit.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this measurement unit references.\n\nThis field is set when this is a catalog-backed measurement unit.", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnit", "properties": [ { "name": "custom_unit", "type": "#/components/schemas/MeasurementUnitCustom", "description": "A custom unit of measurement defined by the seller using the Point of Sale\napp or ad-hoc as an order line item.", "readOnly": false, "required": false }, { "name": "area_unit", "type": "#/components/schemas/MeasurementUnitArea", "description": "Represents a standard area unit.\n", "readOnly": false, "required": false }, { "name": "length_unit", "type": "#/components/schemas/MeasurementUnitLength", "description": "Represents a standard length unit.\n", "readOnly": false, "required": false }, { "name": "volume_unit", "type": "#/components/schemas/MeasurementUnitVolume", "description": "Represents a standard volume unit.\n", "readOnly": false, "required": false }, { "name": "weight_unit", "type": "#/components/schemas/MeasurementUnitWeight", "description": "Represents a standard unit of weight or mass.\n", "readOnly": false, "required": false }, { "name": "generic_unit", "type": "#/components/schemas/MeasurementUnitGeneric", "description": "Reserved for API integrations that lack the ability to specify a real measurement unit\n", "readOnly": false, "required": false }, { "name": "time_unit", "type": "#/components/schemas/MeasurementUnitTime", "description": "Represents a standard unit of time.\n", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/MeasurementUnitUnitType", "description": "Represents the type of the measurement unit.\n", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnitCustom", "properties": [ { "name": "name", "type": "string", "description": "The name of the custom unit, for example \"bushel\".", "readOnly": false, "required": true }, { "name": "abbreviation", "type": "string", "description": "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears\nin the cart for the Point of Sale app, and in reports.", "readOnly": false, "required": true } ] }, { "name": "MeasurementUnitArea", "properties": [] }, { "name": "MeasurementUnitLength", "properties": [] }, { "name": "MeasurementUnitVolume", "properties": [] }, { "name": "MeasurementUnitWeight", "properties": [] }, { "name": "MeasurementUnitGeneric", "properties": [] }, { "name": "MeasurementUnitTime", "properties": [] }, { "name": "MeasurementUnitUnitType", "properties": [] }, { "name": "OrderLineItemItemType", "properties": [] }, { "name": "OrderLineItemModifier", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the modifier only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this modifier references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the item modifier.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0.", "readOnly": false, "required": false }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` will\noverride the predefined [CatalogModifier](entity:CatalogModifier) price.", "readOnly": false, "required": false }, { "name": "total_price_money", "type": "#/components/schemas/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false } ] }, { "name": "OrderLineItemAppliedTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied tax only within this order.", "readOnly": false, "required": false }, { "name": "tax_uid", "type": "string", "description": "The `uid` of the tax for which this applied tax represents. It must reference\na tax present in the `order.taxes` field.\n\nThis field is immutable. To change which taxes apply to a line item, delete and add a new\n`OrderLineItemAppliedTax`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the tax to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemAppliedDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied discount only within this order.", "readOnly": false, "required": false }, { "name": "discount_uid", "type": "string", "description": "The `uid` of the discount that the applied discount represents. It must\nreference a discount present in the `order.discounts` field.\n\nThis field is immutable. To change which discounts apply to a line item,\nyou must delete the discount and re-add it as a new `OrderLineItemAppliedDiscount`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the discount to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemAppliedServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied service charge only within this order.", "readOnly": false, "required": false }, { "name": "service_charge_uid", "type": "string", "description": "The `uid` of the service charge that the applied service charge represents. It must\nreference a service charge present in the `order.service_charges` field.\n\nThis field is immutable. To change which service charges apply to a line item,\ndelete and add a new `OrderLineItemAppliedServiceCharge`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the service charge to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemPricingBlocklists", "properties": [ { "name": "blocked_discounts", "type": "array", "description": "A list of discounts blocked from applying to the line item.\nDiscounts can be blocked by the `discount_uid` (for ad hoc discounts) or\nthe `discount_catalog_object_id` (for catalog discounts).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemPricingBlocklistsBlockedDiscount" }, { "name": "blocked_taxes", "type": "array", "description": "A list of taxes blocked from applying to the line item.\nTaxes can be blocked by the `tax_uid` (for ad hoc taxes) or\nthe `tax_catalog_object_id` (for catalog taxes).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemPricingBlocklistsBlockedTax" } ] }, { "name": "OrderLineItemPricingBlocklistsBlockedDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID of the `BlockedDiscount` within the order.", "readOnly": false, "required": false }, { "name": "discount_uid", "type": "string", "description": "The `uid` of the discount that should be blocked. Use this field to block\nad hoc discounts. For catalog discounts, use the `discount_catalog_object_id` field.", "readOnly": false, "required": false }, { "name": "discount_catalog_object_id", "type": "string", "description": "The `catalog_object_id` of the discount that should be blocked.\nUse this field to block catalog discounts. For ad hoc discounts, use the\n`discount_uid` field.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItemPricingBlocklistsBlockedTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID of the `BlockedTax` within the order.", "readOnly": false, "required": false }, { "name": "tax_uid", "type": "string", "description": "The `uid` of the tax that should be blocked. Use this field to block\nad hoc taxes. For catalog, taxes use the `tax_catalog_object_id` field.", "readOnly": false, "required": false }, { "name": "tax_catalog_object_id", "type": "string", "description": "The `catalog_object_id` of the tax that should be blocked.\nUse this field to block catalog taxes. For ad hoc taxes, use the\n`tax_uid` field.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItemTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the tax only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this tax references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The tax's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal\nnumber. For example, a value of `\"7.25\"` corresponds to a percentage of\n7.25%.", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this tax. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the tax.\n\n- For percentage-based taxes, `applied_money` is the money\ncalculated using the percentage.", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemTaxScope", "description": "Indicates the level at which the tax applies. For `ORDER` scoped taxes,\nSquare generates references in `applied_taxes` on all order line items that do\nnot have them. For `LINE_ITEM` scoped taxes, the tax only applies to line items\nwith references in their `applied_taxes` field.\n\nThis field is immutable. To change the scope, you must delete the tax and\nre-add it as a new tax.\n", "readOnly": false, "required": false }, { "name": "auto_applied", "type": "boolean", "description": "Determines whether the tax was automatically applied to the order based on\nthe catalog configuration. For an example, see\n[Automatically Apply Taxes to an Order](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes).", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemTaxType", "properties": [] }, { "name": "OrderLineItemTaxScope", "properties": [] }, { "name": "OrderLineItemDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the discount only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this discount references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The discount's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemDiscountType", "description": "The type of the discount.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the discount, as a string representation of a decimal number.\nA value of `7.25` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of discount actually applied to the line item.\n\nThe amount represents the amount of money applied as a line-item scoped discount.\nWhen an amount-based discount is scoped to the entire order, the value\nof `applied_money` is different than `amount_money` because the total\namount of the discount is distributed across all line items.", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this discount. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemDiscountScope", "description": "Indicates the level at which the discount applies. For `ORDER` scoped discounts,\nSquare generates references in `applied_discounts` on all order line items that do\nnot have them. For `LINE_ITEM` scoped discounts, the discount only applies to line items\nwith a discount reference in their `applied_discounts` field.\n\nThis field is immutable. To change the scope of a discount, you must delete\nthe discount and re-add it as a new discount.\n", "readOnly": false, "required": false }, { "name": "reward_ids", "type": "array", "description": "The reward IDs corresponding to this discount. The application and\nspecification of discounts that have `reward_ids` are completely controlled by the backing\ncriteria corresponding to the reward tiers of the rewards that are added to the order\nthrough the Loyalty API. To manually unapply discounts that are the result of added rewards,\nthe rewards must be removed from the order through the Loyalty API.", "readOnly": true, "required": false }, { "name": "pricing_rule_id", "type": "string", "description": "The object ID of a [pricing rule](entity:CatalogPricingRule) to be applied\nautomatically to this discount. The specification and application of the discounts, to\nwhich a `pricing_rule_id` is assigned, are completely controlled by the corresponding\npricing rule.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemDiscountType", "properties": [] }, { "name": "OrderLineItemDiscountScope", "properties": [] }, { "name": "OrderServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the service charge only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the service charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing the service charge [CatalogObject](entity:CatalogObject).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this service charge references.", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The service charge percentage as a string representation of a\ndecimal number. For example, `\"7.25\"` indicates a service charge of 7.25%.\n\nExactly 1 of `percentage` or `amount_money` should be set.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of a non-percentage-based service charge.\n\nExactly one of `percentage` or `amount_money` should be set.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the service charge,\nincluding any inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money\ncalculated using the percentage.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the service charge.\n\n__Note__: If an inclusive tax is applied to the service charge,\n`total_money` does not equal `applied_money` plus `total_tax_money`\nbecause the inclusive tax amount is already included in both\n`applied_money` and `total_tax_money`.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/OrderServiceChargeCalculationPhase", "description": "The calculation phase at which to apply the service charge.\n", "readOnly": false, "required": false }, { "name": "taxable", "type": "boolean", "description": "Indicates whether the service charge can be taxed. If set to `true`,\norder-level taxes automatically apply to the service charge. Note that\nservice charges calculated in the `TOTAL_PHASE` cannot be marked as taxable.", "readOnly": false, "required": false }, { "name": "applied_taxes", "type": "array", "description": "The list of references to the taxes applied to this service charge. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderLineItemTax` that is being applied to this service charge. On reads, the amount applied\nis populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every taxable service charge\nfor all `ORDER` scoped taxes that are added to the order. `OrderLineItemAppliedTax` records\nfor `LINE_ITEM` scoped taxes must be added in requests for the tax to apply to any taxable\nservice charge. Taxable service charges have the `taxable` field set to `true` and calculated\nin the `SUBTOTAL_PHASE`.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this service charge. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderServiceChargeType", "description": "The type of the service charge.\n", "readOnly": true, "required": false }, { "name": "treatment_type", "type": "#/components/schemas/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\n", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\n", "readOnly": false, "required": false } ] }, { "name": "OrderServiceChargeCalculationPhase", "properties": [] }, { "name": "OrderServiceChargeType", "properties": [] }, { "name": "OrderServiceChargeTreatmentType", "properties": [] }, { "name": "OrderServiceChargeScope", "properties": [] }, { "name": "Fulfillment", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the fulfillment only within this order.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/FulfillmentType", "description": "The type of the fulfillment.\n", "readOnly": false, "required": false }, { "name": "state", "type": "#/components/schemas/FulfillmentState", "description": "The state of the fulfillment.\n", "readOnly": false, "required": false }, { "name": "line_item_application", "type": "#/components/schemas/FulfillmentFulfillmentLineItemApplication", "description": "Describes what order line items this fulfillment applies to.\nIt can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.\n", "readOnly": true, "required": false }, { "name": "entries", "type": "array", "description": "A list of entries pertaining to the fulfillment of an order. Each entry must reference\na valid `uid` for an order line item in the `line_item_uid` field, as well as a `quantity` to\nfulfill.\n\nMultiple entries can reference the same line item `uid`, as long as the total quantity among\nall fulfillment entries referencing a single line item does not exceed the quantity of the\norder's line item itself.\n\nAn order cannot be marked as `COMPLETED` before all fulfillments are `COMPLETED`,\n`CANCELED`, or `FAILED`. Fulfillments can be created and completed independently\nbefore order completion.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/FulfillmentFulfillmentEntry" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this fulfillment. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "pickup_details", "type": "#/components/schemas/FulfillmentPickupDetails", "description": "Contains details for a pickup fulfillment. These details are required when the fulfillment\ntype is `PICKUP`.", "readOnly": false, "required": false }, { "name": "shipment_details", "type": "#/components/schemas/FulfillmentShipmentDetails", "description": "Contains details for a shipment fulfillment. These details are required when the fulfillment type\nis `SHIPMENT`.\n\nA shipment fulfillment's relationship to fulfillment `state`:\n`PROPOSED`: A shipment is requested.\n`RESERVED`: Fulfillment in progress. Shipment processing.\n`PREPARED`: Shipment packaged. Shipping label created.\n`COMPLETED`: Package has been shipped.\n`CANCELED`: Shipment has been canceled.\n`FAILED`: Shipment has failed.", "readOnly": false, "required": false }, { "name": "delivery_details", "type": "#/components/schemas/FulfillmentDeliveryDetails", "description": "Describes delivery details of an order fulfillment.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentType", "properties": [] }, { "name": "FulfillmentState", "properties": [] }, { "name": "FulfillmentFulfillmentLineItemApplication", "properties": [] }, { "name": "FulfillmentFulfillmentEntry", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the fulfillment entry only within this order.", "readOnly": false, "required": false }, { "name": "line_item_uid", "type": "string", "description": "The `uid` from the order line item.", "readOnly": false, "required": true }, { "name": "quantity", "type": "string", "description": "The quantity of the line item being fulfilled, formatted as a decimal number.\nFor example, `\"3\"`.\n\nFulfillments for line items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "readOnly": false, "required": true }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this fulfillment entry. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false } ] }, { "name": "FulfillmentPickupDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "Information about the person to pick up this fulfillment from a physical\nlocation.", "readOnly": false, "required": false }, { "name": "expires_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment expires if it is not marked in progress. The timestamp must be\nin RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\"). The expiration time can only be set\nup to 7 days in the future. If `expires_at` is not set, any new payments attached to the order\nare automatically completed.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "auto_complete_duration", "type": "string", "description": "The duration of time after which an in progress pickup fulfillment is automatically moved\nto the `COMPLETED` state. The duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nIf not set, this pickup fulfillment remains in progress until it is canceled or completed.\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "schedule_type", "type": "#/components/schemas/FulfillmentPickupDetailsScheduleType", "description": "The schedule type of the pickup fulfillment. Defaults to `SCHEDULED`.\n", "readOnly": false, "required": false }, { "name": "pickup_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the pickup window. Must be in RFC 3339 timestamp format, e.g.,\n\"2016-09-04T23:59:33.123Z\".\n\nFor fulfillments with the schedule type `ASAP`, this is automatically set\nto the current time plus the expected duration to prepare the fulfillment.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "pickup_window_duration", "type": "string", "description": "The window of time in which the order should be picked up after the `pickup_at` timestamp.\nMust be in RFC 3339 duration format, e.g., \"P1W3D\". Can be used as an\ninformational guideline for merchants.\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "prep_time_duration", "type": "string", "description": "The duration of time it takes to prepare this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "A note to provide additional instructions about the pickup\nfulfillment displayed in the Square Point of Sale application and set by the API.", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "accepted_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was marked in progress. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "rejected_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "ready_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment is marked as ready for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "expired_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment expired. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "picked_up_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was picked up by the recipient. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "string", "description": "A description of why the pickup was canceled. The maximum length: 100 characters.", "readOnly": false, "required": false }, { "name": "is_curbside_pickup", "type": "boolean", "description": "If set to `true`, indicates that this pickup order is for curbside pickup, not in-store pickup.", "readOnly": false, "required": false }, { "name": "curbside_pickup_details", "type": "#/components/schemas/FulfillmentPickupDetailsCurbsidePickupDetails", "description": "Specific details for curbside pickup. These details can only be populated if `is_curbside_pickup` is set to `true`.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentRecipient", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer associated with the fulfillment.\n\nIf `customer_id` is provided, the fulfillment recipient's `display_name`,\n`email_address`, and `phone_number` are automatically populated from the\ntargeted customer profile. If these fields are set in the request, the request\nvalues override the information from the customer profile. If the\ntargeted customer profile does not contain the necessary information and\nthese fields are left unset, the request results in an error.", "readOnly": false, "required": false }, { "name": "display_name", "type": "string", "description": "The display name of the fulfillment recipient. This field is required.\n\nIf provided, the display name overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "email_address", "type": "string", "description": "The email address of the fulfillment recipient.\n\nIf provided, the email address overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number of the fulfillment recipient. This field is required.\n\nIf provided, the phone number overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The address of the fulfillment recipient. This field is required.\n\nIf provided, the address overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "FulfillmentPickupDetailsScheduleType", "properties": [] }, { "name": "FulfillmentPickupDetailsCurbsidePickupDetails", "properties": [ { "name": "curbside_details", "type": "string", "description": "Specific details for curbside pickup, such as parking number and vehicle model.", "readOnly": false, "required": false }, { "name": "buyer_arrived_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the buyer arrived and is waiting for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false } ] }, { "name": "FulfillmentShipmentDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "Information about the person to receive this shipment fulfillment.", "readOnly": false, "required": false }, { "name": "carrier", "type": "string", "description": "The shipping carrier being used to ship this fulfillment (such as UPS, FedEx, or USPS).", "readOnly": false, "required": false }, { "name": "shipping_note", "type": "string", "description": "A note with additional information for the shipping carrier.", "readOnly": false, "required": false }, { "name": "shipping_type", "type": "string", "description": "A description of the type of shipping product purchased from the carrier\n(such as First Class, Priority, or Express).", "readOnly": false, "required": false }, { "name": "tracking_number", "type": "string", "description": "The reference number provided by the carrier to track the shipment's progress.", "readOnly": false, "required": false }, { "name": "tracking_url", "type": "string", "description": "A link to the tracking webpage on the carrier's website.", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment was requested. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "in_progress_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `RESERVED` state, which indicates that preparation\nof this shipment has begun. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "packaged_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `PREPARED` state, which indicates that the\nfulfillment is packaged. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "expected_shipped_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment is expected to be delivered to the shipping carrier.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "shipped_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `COMPLETED` state, which indicates that\nthe fulfillment has been given to the shipping carrier. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating the shipment was canceled.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "cancel_reason", "type": "string", "description": "A description of why the shipment was canceled.", "readOnly": false, "required": false }, { "name": "failed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment failed to be completed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "failure_reason", "type": "string", "description": "A description of why the shipment failed to be completed.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentDeliveryDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "The contact information for the person to receive the fulfillment.", "readOnly": false, "required": false }, { "name": "schedule_type", "type": "#/components/schemas/FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType", "description": "Indicates the fulfillment delivery schedule type. If `SCHEDULED`, then\n`deliver_at` is required. If `ASAP`, then `prep_time_duration` is required. The default is `SCHEDULED`.\n", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nMust be in RFC 3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "deliver_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the delivery period.\nWhen the fulfillment `schedule_type` is `ASAP`, the field is automatically\nset to the current time plus the `prep_time_duration`.\nOtherwise, the application can set this field while the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the\nterminal state such as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "prep_time_duration", "type": "string", "description": "The duration of time it takes to prepare and deliver this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "delivery_window_duration", "type": "string", "description": "The time period after `deliver_at` in which to deliver the order.\nApplications can set this field when the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the terminal state\nsuch as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "Provides additional instructions about the delivery fulfillment.\nIt is displayed in the Square Point of Sale application and set by the API.", "readOnly": false, "required": false }, { "name": "completed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller completed the fulfillment.\nThis field is automatically set when fulfillment `state` changes to `COMPLETED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "in_progress_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller started processing the fulfillment.\nThis field is automatically set when the fulfillment `state` changes to `RESERVED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "rejected_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. This field is\nautomatically set when the fulfillment `state` changes to `FAILED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "ready_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the seller marked the fulfillment as ready for\ncourier pickup. This field is automatically set when the fulfillment `state` changes\nto PREPARED.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "delivered_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was delivered to the recipient.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. This field is automatically\nset when the fulfillment `state` changes to `CANCELED`.\n\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "string", "description": "The delivery cancellation reason. Max length: 100 characters.", "readOnly": false, "required": false }, { "name": "courier_pickup_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when an order can be picked up by the courier for delivery.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "courier_pickup_window_duration", "type": "string", "description": "The time period after `courier_pickup_at` in which the courier should pick up the order.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "is_no_contact_delivery", "type": "boolean", "description": "Whether the delivery is preferred to be no contact.", "readOnly": false, "required": false }, { "name": "dropoff_notes", "type": "string", "description": "A note to provide additional instructions about how to deliver the order.", "readOnly": false, "required": false }, { "name": "courier_provider_name", "type": "string", "description": "The name of the courier provider.", "readOnly": false, "required": false }, { "name": "courier_support_phone_number", "type": "string", "description": "The support phone number of the courier.", "readOnly": false, "required": false }, { "name": "square_delivery_id", "type": "string", "description": "The identifier for the delivery created by Square.", "readOnly": false, "required": false }, { "name": "external_delivery_id", "type": "string", "description": "The identifier for the delivery created by the third-party courier service.", "readOnly": false, "required": false }, { "name": "managed_delivery", "type": "boolean", "description": "The flag to indicate the delivery is managed by a third party (ie DoorDash), which means\nwe may not receive all recipient information for PII purposes.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType", "properties": [] }, { "name": "OrderReturn", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return only within this order.", "readOnly": false, "required": false }, { "name": "source_order_id", "type": "string", "description": "An order that contains the original sale of these return line items. This is unset\nfor unlinked returns.", "readOnly": false, "required": false }, { "name": "return_line_items", "type": "array", "description": "A collection of line items that are being returned.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnLineItem" }, { "name": "return_service_charges", "type": "array", "description": "A collection of service charges that are being returned.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnServiceCharge" }, { "name": "return_taxes", "type": "array", "description": "A collection of references to taxes being returned for an order, including the total\napplied tax amount to be returned. The taxes must reference a top-level tax ID from the source\norder.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturnTax" }, { "name": "return_discounts", "type": "array", "description": "A collection of references to discounts being returned for an order, including the total\napplied discount amount to be returned. The discounts must reference a top-level discount ID\nfrom the source order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturnDiscount" }, { "name": "return_tips", "type": "array", "description": "A collection of references to tips being returned for an order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnTip" }, { "name": "rounding_adjustment", "type": "#/components/schemas/OrderRoundingAdjustment", "description": "A positive or negative rounding adjustment to the total value being returned. Adjustments are commonly\nused to apply cash rounding when the minimum unit of the account is smaller than the lowest\nphysical denomination of the currency.", "readOnly": false, "required": false }, { "name": "return_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "An aggregate monetary value being returned by this return entry.", "readOnly": false, "required": false } ] }, { "name": "OrderReturnLineItem", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID for this return line-item entry.", "readOnly": false, "required": false }, { "name": "source_line_item_uid", "type": "string", "description": "The `uid` of the line item in the original sale order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the line item.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity returned, formatted as a decimal number.\nFor example, `\"3\"`.\n\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "readOnly": false, "required": true }, { "name": "quantity_unit", "type": "#/components/schemas/OrderQuantityUnit", "description": "The unit and precision that this return line item's quantity is measured in.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "The note of the return line item.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this return line item.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item references.", "readOnly": false, "required": false }, { "name": "variation_name", "type": "string", "description": "The name of the variation applied to this return line item.", "readOnly": false, "required": false }, { "name": "item_type", "type": "#/components/schemas/OrderLineItemItemType", "description": "The type of line item: an itemized return, a non-itemized return (custom amount),\nor the return of an unactivated gift card sale.\n", "readOnly": false, "required": false }, { "name": "return_modifiers", "type": "array", "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnLineItemModifier" }, { "name": "applied_taxes", "type": "array", "description": "The list of references to `OrderReturnTax` entities applied to the return line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderReturnTax` applied to the return line item. On reads, the applied amount\nis populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "applied_discounts", "type": "array", "description": "The list of references to `OrderReturnDiscount` entities applied to the return line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderReturnDiscount` applied to the return line item. On reads, the applied amount\nis populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedDiscount" }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for a single unit of the line item.", "readOnly": false, "required": false }, { "name": "variation_total_price_money", "type": "#/components/schemas/Money", "description": "The total price of all item variations returned in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity` and\ndoes not include modifiers.", "readOnly": true, "required": false }, { "name": "gross_return_money", "type": "#/components/schemas/Money", "description": "The gross return amount of money calculated as (item base price + modifiers price) * quantity.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to return for the line item.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to return for the line item.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to return for this line item.", "readOnly": true, "required": false }, { "name": "applied_service_charges", "type": "array", "description": "The list of references to `OrderReturnServiceCharge` entities applied to the return\nline item. Each `OrderLineItemAppliedServiceCharge` has a `service_charge_uid` that\nreferences the `uid` of a top-level `OrderReturnServiceCharge` applied to the return line\nitem. On reads, the applied amount is populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedServiceCharge" }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of apportioned service charge money to return for the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderReturnLineItemModifier", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return modifier only within this order.", "readOnly": false, "required": false }, { "name": "source_modifier_uid", "type": "string", "description": "The modifier `uid` from the order's line item that contains the\noriginal sale of this line item modifier.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item modifier references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the item modifier.", "readOnly": false, "required": false }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` overrides the predefined [CatalogModifier](entity:CatalogModifier) price.", "readOnly": false, "required": false }, { "name": "total_price_money", "type": "#/components/schemas/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0.", "readOnly": false, "required": false } ] }, { "name": "OrderReturnServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return service charge only within this order.", "readOnly": false, "required": false }, { "name": "source_service_charge_uid", "type": "string", "description": "The service charge `uid` from the order containing the original\nservice charge. `source_service_charge_uid` is `null` for\nunlinked returns.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the service charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID of the associated [OrderServiceCharge](entity:OrderServiceCharge).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this service charge references.", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "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%.\n\nEither `percentage` or `amount_money` should be set, but not both.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of a non-percentage-based service charge.\n\nEither `percentage` or `amount_money` should be set, but not both.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the service charge, including\nany inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money calculated using the percentage.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the service charge.\n\n__NOTE__: If an inclusive tax is applied to the service charge, `total_money`\ndoes not equal `applied_money` plus `total_tax_money` because the inclusive\ntax amount is already included in both `applied_money` and `total_tax_money`.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/OrderServiceChargeCalculationPhase", "description": "The calculation phase after which to apply the service charge.\n", "readOnly": true, "required": false }, { "name": "taxable", "type": "boolean", "description": "Indicates whether the surcharge can be taxed. Service charges\ncalculated in the `TOTAL_PHASE` cannot be marked as taxable.", "readOnly": false, "required": false }, { "name": "applied_taxes", "type": "array", "description": "The list of references to `OrderReturnTax` entities applied to the\n`OrderReturnServiceCharge`. Each `OrderLineItemAppliedTax` has a `tax_uid`\nthat references the `uid` of a top-level `OrderReturnTax` that is being\napplied to the `OrderReturnServiceCharge`. On reads, the applied amount is\npopulated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "treatment_type", "type": "#/components/schemas/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\n", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the returned tax only within this order.", "readOnly": false, "required": false }, { "name": "source_tax_uid", "type": "string", "description": "The tax `uid` from the order that contains the original tax charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this tax references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The tax's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal number.\nFor example, a value of `\"7.25\"` corresponds to a percentage of 7.25%.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the tax in an order.", "readOnly": true, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemTaxScope", "description": "Indicates the level at which the `OrderReturnTax` applies. For `ORDER` scoped\ntaxes, Square generates references in `applied_taxes` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the returned discount only within this order.", "readOnly": false, "required": false }, { "name": "source_discount_uid", "type": "string", "description": "The discount `uid` from the order that contains the original application of this discount.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this discount references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The discount's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemDiscountType", "description": "The type of the discount. If it is created by the API, it is `FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal number.\nA value of `\"7.25\"` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of discount actually applied to this line item. When an amount-based\ndiscount is at the order level, this value is different from `amount_money` because the discount\nis distributed across the line items.", "readOnly": true, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemDiscountScope", "description": "Indicates the level at which the `OrderReturnDiscount` applies. For `ORDER` scoped\ndiscounts, the server generates references in `applied_discounts` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the discount is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnTip", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the tip only within this order.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of tip being returned\n--", "readOnly": true, "required": false }, { "name": "source_tender_uid", "type": "string", "description": "The tender `uid` from the order that contains the original application of this tip.", "readOnly": false, "required": false }, { "name": "source_tender_id", "type": "string", "description": "The tender `id` from the order that contains the original application of this tip.", "readOnly": false, "required": false } ] }, { "name": "OrderRoundingAdjustment", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the rounding adjustment only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the rounding adjustment from the original sale order.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The actual rounding adjustment amount.", "readOnly": false, "required": false } ] }, { "name": "OrderMoneyAmounts", "properties": [ { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total money.", "readOnly": false, "required": false }, { "name": "tax_money", "type": "#/components/schemas/Money", "description": "The money associated with taxes.", "readOnly": false, "required": false }, { "name": "discount_money", "type": "#/components/schemas/Money", "description": "The money associated with discounts.", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The money associated with tips.", "readOnly": false, "required": false }, { "name": "service_charge_money", "type": "#/components/schemas/Money", "description": "The money associated with service charges.", "readOnly": false, "required": false } ] }, { "name": "Tender", "properties": [ { "name": "id", "type": "string", "description": "The tender's unique ID. It is the associated payment ID.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the transaction's associated location.", "readOnly": false, "required": false }, { "name": "transaction_id", "type": "string", "description": "The ID of the tender's associated transaction.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp for when the tender was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "note", "type": "string", "description": "An optional note associated with the tender at the time of payment.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total amount of the tender, including `tip_money`. If the tender has a `payment_id`,\nthe `total_money` of the corresponding [Payment](entity:Payment) will be equal to the\n`amount_money` of the tender.", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The tip's amount of the tender.", "readOnly": false, "required": false }, { "name": "processing_fee_money", "type": "#/components/schemas/Money", "description": "The amount of any Square processing fees applied to the tender.\n\nThis field is not immediately populated when a new transaction is created.\nIt is usually available after about ten seconds.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "If the tender is associated with a customer or represents a customer's card on file,\nthis is the ID of the associated customer.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/TenderType", "description": "The type of tender, such as `CARD` or `CASH`.\n", "readOnly": false, "required": true }, { "name": "card_details", "type": "#/components/schemas/TenderCardDetails", "description": "The details of the card tender.\n\nThis value is present only if the value of `type` is `CARD`.", "readOnly": false, "required": false }, { "name": "cash_details", "type": "#/components/schemas/TenderCashDetails", "description": "The details of the cash tender.\n\nThis value is present only if the value of `type` is `CASH`.", "readOnly": false, "required": false }, { "name": "bank_account_details", "type": "#/components/schemas/TenderBankAccountDetails", "description": "The details of the bank account tender.\n\nThis value is present only if the value of `type` is `BANK_ACCOUNT`.", "readOnly": false, "required": false }, { "name": "buy_now_pay_later_details", "type": "#/components/schemas/TenderBuyNowPayLaterDetails", "description": "The details of a Buy Now Pay Later tender.\n\nThis value is present only if the value of `type` is `BUY_NOW_PAY_LATER`.", "readOnly": false, "required": false }, { "name": "square_account_details", "type": "#/components/schemas/TenderSquareAccountDetails", "description": "The details of a Square Account tender.\n\nThis value is present only if the value of `type` is `SQUARE_ACCOUNT`.", "readOnly": false, "required": false }, { "name": "additional_recipients", "type": "array", "description": "Additional recipients (other than the merchant) receiving a portion of this tender.\nFor example, fees assessed on the purchase by a third party integration.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/AdditionalRecipient" }, { "name": "payment_id", "type": "string", "description": "The ID of the [Payment](entity:Payment) that corresponds to this tender.\nThis value is only present for payments created with the v2 Payments API.", "readOnly": false, "required": false } ] }, { "name": "TenderType", "properties": [] }, { "name": "TenderCardDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderCardDetailsStatus", "description": "The credit card payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderCardDetailsStatus](entity:TenderCardDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false }, { "name": "card", "type": "#/components/schemas/Card", "description": "The credit card's non-confidential details.", "readOnly": false, "required": false }, { "name": "entry_method", "type": "#/components/schemas/TenderCardDetailsEntryMethod", "description": "The method used to enter the card's details for the transaction.\n", "readOnly": false, "required": false } ] }, { "name": "TenderCardDetailsStatus", "properties": [] }, { "name": "Card", "properties": [ { "name": "id", "type": "string", "description": "Unique ID for this card. Generated by Square.", "readOnly": true, "required": false }, { "name": "card_brand", "type": "#/components/schemas/CardBrand", "description": "The card's brand.\n", "readOnly": true, "required": false }, { "name": "last_4", "type": "string", "description": "The last 4 digits of the card number.", "readOnly": true, "required": false }, { "name": "exp_month", "type": "integer", "description": "The expiration month of the associated card as an integer between 1 and 12.", "readOnly": false, "required": false }, { "name": "exp_year", "type": "integer", "description": "The four-digit year of the card's expiration date.", "readOnly": false, "required": false }, { "name": "cardholder_name", "type": "string", "description": "The name of the cardholder.", "readOnly": false, "required": false }, { "name": "billing_address", "type": "#/components/schemas/Address", "description": "The billing address for this card.", "readOnly": false, "required": false }, { "name": "fingerprint", "type": "string", "description": "Intended as a Square-assigned identifier, based\non the card number, to identify the card across multiple locations within a\nsingle application.", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "**Required** The ID of a customer created using the Customers API to be associated with the card.", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the merchant associated with the card.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional user-defined reference ID that associates this card with\nanother entity in an external system. For example, a customer ID from an\nexternal customer management system.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "Indicates whether or not a card can be used for payments.", "readOnly": true, "required": false }, { "name": "card_type", "type": "#/components/schemas/CardType", "description": "The type of the card.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "prepaid_type", "type": "#/components/schemas/CardPrepaidType", "description": "Indicates whether the Card is prepaid or not.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "bin", "type": "string", "description": "The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API\nreturns this field.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "Current version number of the card. Increments with each card update. Requests to update an\nexisting Card object will be rejected unless the version in the request matches the current\nversion for the Card.", "readOnly": false, "required": false }, { "name": "card_co_brand", "type": "#/components/schemas/CardCoBrand", "description": "The card's co-brand if available. For example, an Afterpay virtual card would have a\nco-brand of AFTERPAY.\n", "readOnly": true, "required": false } ] }, { "name": "CardBrand", "properties": [] }, { "name": "CardType", "properties": [] }, { "name": "CardPrepaidType", "properties": [] }, { "name": "CardCoBrand", "properties": [] }, { "name": "TenderCardDetailsEntryMethod", "properties": [] }, { "name": "TenderCashDetails", "properties": [ { "name": "buyer_tendered_money", "type": "#/components/schemas/Money", "description": "The total amount of cash provided by the buyer, before change is given.", "readOnly": false, "required": false }, { "name": "change_back_money", "type": "#/components/schemas/Money", "description": "The amount of change returned to the buyer.", "readOnly": false, "required": false } ] }, { "name": "TenderBankAccountDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderBankAccountDetailsStatus", "description": "The bank account payment's current state.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "TenderBankAccountDetailsStatus", "properties": [] }, { "name": "TenderBuyNowPayLaterDetails", "properties": [ { "name": "buy_now_pay_later_brand", "type": "#/components/schemas/TenderBuyNowPayLaterDetailsBrand", "description": "The Buy Now Pay Later brand.\n", "readOnly": true, "required": false }, { "name": "status", "type": "#/components/schemas/TenderBuyNowPayLaterDetailsStatus", "description": "The buy now pay later payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderBuyNowPayLaterDetailsStatus](entity:TenderBuyNowPayLaterDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false } ] }, { "name": "TenderBuyNowPayLaterDetailsBrand", "properties": [] }, { "name": "TenderBuyNowPayLaterDetailsStatus", "properties": [] }, { "name": "TenderSquareAccountDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderSquareAccountDetailsStatus", "description": "The Square Account payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderSquareAccountDetailsStatus](entity:TenderSquareAccountDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false } ] }, { "name": "TenderSquareAccountDetailsStatus", "properties": [] }, { "name": "AdditionalRecipient", "properties": [ { "name": "location_id", "type": "string", "description": "The location ID for a recipient (other than the merchant) receiving a portion of this tender.", "readOnly": false, "required": true }, { "name": "description", "type": "string", "description": "The description of the additional recipient.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money distributed to the recipient.", "readOnly": false, "required": true }, { "name": "receivable_id", "type": "string", "description": "The unique ID for the RETIRED `AdditionalRecipientReceivable` object. This field should be empty for any `AdditionalRecipient` objects created after the retirement.", "readOnly": false, "required": false } ] }, { "name": "Refund", "properties": [ { "name": "id", "type": "string", "description": "The refund's unique ID.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The ID of the refund's associated location.", "readOnly": false, "required": true }, { "name": "transaction_id", "type": "string", "description": "The ID of the transaction that the refunded tender is part of.", "readOnly": false, "required": false }, { "name": "tender_id", "type": "string", "description": "The ID of the refunded tender.", "readOnly": false, "required": true }, { "name": "created_at", "type": "string", "description": "The timestamp for when the refund was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "reason", "type": "string", "description": "The reason for the refund being issued.", "readOnly": false, "required": true }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money refunded to the buyer.", "readOnly": false, "required": true }, { "name": "status", "type": "#/components/schemas/RefundStatus", "description": "The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`,\nor `FAILED`).\n", "readOnly": false, "required": true }, { "name": "processing_fee_money", "type": "#/components/schemas/Money", "description": "The amount of Square processing fee money refunded to the *merchant*.", "readOnly": false, "required": false }, { "name": "additional_recipients", "type": "array", "description": "Additional recipients (other than the merchant) receiving a portion of this refund.\nFor example, fees assessed on a refund of a purchase by a third party integration.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/AdditionalRecipient" } ] }, { "name": "RefundStatus", "properties": [] }, { "name": "OrderState", "properties": [] }, { "name": "OrderPricingOptions", "properties": [ { "name": "auto_apply_discounts", "type": "boolean", "description": "The option to determine whether pricing rule-based\ndiscounts are automatically applied to an order.", "readOnly": false, "required": false }, { "name": "auto_apply_taxes", "type": "boolean", "description": "The option to determine whether rule-based taxes are automatically\napplied to an order when the criteria of the corresponding rules are met.", "readOnly": false, "required": false } ] }, { "name": "OrderReward", "properties": [ { "name": "id", "type": "string", "description": "The identifier of the reward.", "readOnly": false, "required": true }, { "name": "reward_tier_id", "type": "string", "description": "The identifier of the reward tier corresponding to this reward.", "readOnly": false, "required": true } ] }, { "name": "CheckoutOptions", "properties": [ { "name": "allow_tipping", "type": "boolean", "description": "Indicates whether the payment allows tipping.", "readOnly": false, "required": false }, { "name": "custom_fields", "type": "array", "description": "The custom fields requesting information from the buyer.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CustomField" }, { "name": "subscription_plan_id", "type": "string", "description": "The ID of the subscription plan for the buyer to pay and subscribe.\nFor more information, see [Subscription Plan Checkout](https://developer.squareup.com/docs/checkout-api/subscription-plan-checkout).", "readOnly": false, "required": false }, { "name": "redirect_url", "type": "string", "description": "The confirmation page URL to redirect the buyer to after Square processes the payment.", "readOnly": false, "required": false }, { "name": "merchant_support_email", "type": "string", "description": "The email address that buyers can use to contact the seller.", "readOnly": false, "required": false }, { "name": "ask_for_shipping_address", "type": "boolean", "description": "Indicates whether to include the address fields in the payment form.", "readOnly": false, "required": false }, { "name": "accepted_payment_methods", "type": "#/components/schemas/AcceptedPaymentMethods", "description": "The methods allowed for buyers during checkout.", "readOnly": false, "required": false }, { "name": "app_fee_money", "type": "#/components/schemas/Money", "description": "The amount of money that the developer is taking as a fee for facilitating the payment on behalf of the seller.\n\nThe amount cannot be more than 90% of the total amount of the payment.\n\nThe amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/common-data-types/working-with-monetary-amounts).\n\nThe fee currency code must match the currency associated with the seller that is accepting the payment. The application must be from a developer account in the same country and using the same currency code as the seller. For more information about the application fee scenario, see [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).\n\nTo set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required. For more information, see [Permissions](https://developer.squareup.com/docs/payments-api/collect-fees/additional-considerations#permissions).", "readOnly": false, "required": false }, { "name": "shipping_fee", "type": "#/components/schemas/ShippingFee", "description": "The fee associated with shipping to be applied to the `Order` as a service charge.", "readOnly": false, "required": false }, { "name": "enable_coupon", "type": "boolean", "description": "Indicates whether to include the `Add coupon` section for the buyer to provide a Square marketing coupon in the payment form.", "readOnly": false, "required": false }, { "name": "enable_loyalty", "type": "boolean", "description": "Indicates whether to include the `REWARDS` section for the buyer to opt in to loyalty, redeem rewards in the payment form, or both.", "readOnly": false, "required": false } ] }, { "name": "CustomField", "properties": [ { "name": "title", "type": "string", "description": "The title of the custom field.", "readOnly": false, "required": true } ] }, { "name": "AcceptedPaymentMethods", "properties": [ { "name": "apple_pay", "type": "boolean", "description": "Whether Apple Pay is accepted at checkout.", "readOnly": false, "required": false }, { "name": "google_pay", "type": "boolean", "description": "Whether Google Pay is accepted at checkout.", "readOnly": false, "required": false }, { "name": "cash_app_pay", "type": "boolean", "description": "Whether Cash App Pay is accepted at checkout.", "readOnly": false, "required": false }, { "name": "afterpay_clearpay", "type": "boolean", "description": "Whether Afterpay/Clearpay is accepted at checkout.", "readOnly": false, "required": false } ] }, { "name": "ShippingFee", "properties": [ { "name": "name", "type": "string", "description": "The name for the shipping fee.", "readOnly": false, "required": false }, { "name": "charge", "type": "#/components/schemas/Money", "description": "The amount and currency for the shipping fee.", "readOnly": false, "required": true } ] }, { "name": "PrePopulatedData", "properties": [ { "name": "buyer_email", "type": "string", "description": "The buyer email to prepopulate in the payment form.", "readOnly": false, "required": false }, { "name": "buyer_phone_number", "type": "string", "description": "The buyer phone number to prepopulate in the payment form.", "readOnly": false, "required": false }, { "name": "buyer_address", "type": "#/components/schemas/Address", "description": "The buyer address to prepopulate in the payment form.", "readOnly": false, "required": false } ] } ], "DeletePaymentLinkRequest": [ { "name": "DeletePaymentLinkRequest", "properties": [ { "name": "id", "type": "string", "description": "The ID of the payment link to delete.", "readOnly": false, "required": true } ] } ], "RetrievePaymentLinkRequest": [ { "name": "RetrievePaymentLinkRequest", "properties": [ { "name": "id", "type": "string", "description": "The ID of link to retrieve.", "readOnly": false, "required": true } ] } ], "UpdatePaymentLinkRequest": [ { "name": "UpdatePaymentLinkRequest", "properties": [ { "name": "payment_link", "type": "#/components/schemas/PaymentLink", "description": "The `payment_link` object describing the updates to apply.\nFor more information, see [Update a payment link](https://developer.squareup.com/docs/checkout-api/manage-checkout#update-a-payment-link).", "readOnly": false, "required": true }, { "name": "id", "type": "string", "description": "The ID of the payment link to update.", "readOnly": false, "required": true } ] }, { "name": "PaymentLink", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the payment link.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "The Square-assigned version number, which is incremented each time an update is committed to the payment link.", "readOnly": false, "required": true }, { "name": "description", "type": "string", "description": "The optional description of the `payment_link` object.\nIt is primarily for use by your application and is not used anywhere.", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the order associated with the payment link.", "readOnly": true, "required": false }, { "name": "checkout_options", "type": "#/components/schemas/CheckoutOptions", "description": "The checkout options configured for the payment link.\nFor more information, see [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations).", "readOnly": false, "required": false }, { "name": "pre_populated_data", "type": "#/components/schemas/PrePopulatedData", "description": "Describes buyer data to prepopulate\non the checkout page.", "readOnly": false, "required": false }, { "name": "url", "type": "string", "description": "The shortened URL of the payment link.", "readOnly": true, "required": false }, { "name": "long_url", "type": "string", "description": "The long URL of the payment link.", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the payment link was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the payment link was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "payment_note", "type": "string", "description": "An optional note. After Square processes the payment, this note is added to the\nresulting `Payment`.", "readOnly": false, "required": false } ] }, { "name": "CheckoutOptions", "properties": [ { "name": "allow_tipping", "type": "boolean", "description": "Indicates whether the payment allows tipping.", "readOnly": false, "required": false }, { "name": "custom_fields", "type": "array", "description": "The custom fields requesting information from the buyer.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CustomField" }, { "name": "subscription_plan_id", "type": "string", "description": "The ID of the subscription plan for the buyer to pay and subscribe.\nFor more information, see [Subscription Plan Checkout](https://developer.squareup.com/docs/checkout-api/subscription-plan-checkout).", "readOnly": false, "required": false }, { "name": "redirect_url", "type": "string", "description": "The confirmation page URL to redirect the buyer to after Square processes the payment.", "readOnly": false, "required": false }, { "name": "merchant_support_email", "type": "string", "description": "The email address that buyers can use to contact the seller.", "readOnly": false, "required": false }, { "name": "ask_for_shipping_address", "type": "boolean", "description": "Indicates whether to include the address fields in the payment form.", "readOnly": false, "required": false }, { "name": "accepted_payment_methods", "type": "#/components/schemas/AcceptedPaymentMethods", "description": "The methods allowed for buyers during checkout.", "readOnly": false, "required": false }, { "name": "app_fee_money", "type": "#/components/schemas/Money", "description": "The amount of money that the developer is taking as a fee for facilitating the payment on behalf of the seller.\n\nThe amount cannot be more than 90% of the total amount of the payment.\n\nThe amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/common-data-types/working-with-monetary-amounts).\n\nThe fee currency code must match the currency associated with the seller that is accepting the payment. The application must be from a developer account in the same country and using the same currency code as the seller. For more information about the application fee scenario, see [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).\n\nTo set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required. For more information, see [Permissions](https://developer.squareup.com/docs/payments-api/collect-fees/additional-considerations#permissions).", "readOnly": false, "required": false }, { "name": "shipping_fee", "type": "#/components/schemas/ShippingFee", "description": "The fee associated with shipping to be applied to the `Order` as a service charge.", "readOnly": false, "required": false }, { "name": "enable_coupon", "type": "boolean", "description": "Indicates whether to include the `Add coupon` section for the buyer to provide a Square marketing coupon in the payment form.", "readOnly": false, "required": false }, { "name": "enable_loyalty", "type": "boolean", "description": "Indicates whether to include the `REWARDS` section for the buyer to opt in to loyalty, redeem rewards in the payment form, or both.", "readOnly": false, "required": false } ] }, { "name": "CustomField", "properties": [ { "name": "title", "type": "string", "description": "The title of the custom field.", "readOnly": false, "required": true } ] }, { "name": "AcceptedPaymentMethods", "properties": [ { "name": "apple_pay", "type": "boolean", "description": "Whether Apple Pay is accepted at checkout.", "readOnly": false, "required": false }, { "name": "google_pay", "type": "boolean", "description": "Whether Google Pay is accepted at checkout.", "readOnly": false, "required": false }, { "name": "cash_app_pay", "type": "boolean", "description": "Whether Cash App Pay is accepted at checkout.", "readOnly": false, "required": false }, { "name": "afterpay_clearpay", "type": "boolean", "description": "Whether Afterpay/Clearpay is accepted at checkout.", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "ShippingFee", "properties": [ { "name": "name", "type": "string", "description": "The name for the shipping fee.", "readOnly": false, "required": false }, { "name": "charge", "type": "#/components/schemas/Money", "description": "The amount and currency for the shipping fee.", "readOnly": false, "required": true } ] }, { "name": "PrePopulatedData", "properties": [ { "name": "buyer_email", "type": "string", "description": "The buyer email to prepopulate in the payment form.", "readOnly": false, "required": false }, { "name": "buyer_phone_number", "type": "string", "description": "The buyer phone number to prepopulate in the payment form.", "readOnly": false, "required": false }, { "name": "buyer_address", "type": "#/components/schemas/Address", "description": "The buyer address to prepopulate in the payment form.", "readOnly": false, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] } ], "ListCustomerCustomAttributeDefinitionsRequest": [ { "name": "ListCustomerCustomAttributeDefinitionsRequest", "properties": [ { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] } ], "CreateCustomerCustomAttributeDefinitionRequest": [ { "name": "CreateCustomerCustomAttributeDefinitionRequest", "properties": [ { "name": "custom_attribute_definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "The custom attribute definition to create. Note the following:\n- With the exception of the `Selection` data type, the `schema` is specified as a simple URL to the JSON schema\ndefinition hosted on the Square CDN. For more information, including supported values and constraints, see\n[Specifying the schema](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attribute-definitions#specify-schema).\n- If provided, `name` must be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller.\n- All custom attributes are visible in exported customer data, including those set to `VISIBILITY_HIDDEN`.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false } ] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] } ], "DeleteCustomerCustomAttributeDefinitionRequest": [ { "name": "DeleteCustomerCustomAttributeDefinitionRequest", "properties": [ { "name": "key", "type": "string", "description": "The key of the custom attribute definition to delete.", "readOnly": false, "required": true } ] } ], "RetrieveCustomerCustomAttributeDefinitionRequest": [ { "name": "RetrieveCustomerCustomAttributeDefinitionRequest", "properties": [ { "name": "version", "type": "integer", "description": "The current version of the custom attribute definition, which is used for strongly consistent\nreads to guarantee that you receive the most up-to-date data. When included in the request,\nSquare returns the specified version or a higher version if one exists. If the specified version\nis higher than the current version, Square returns a `BAD_REQUEST` error.", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "The key of the custom attribute definition to retrieve. If the requesting application\nis not the definition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "UpdateCustomerCustomAttributeDefinitionRequest": [ { "name": "UpdateCustomerCustomAttributeDefinitionRequest", "properties": [ { "name": "custom_attribute_definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "The custom attribute definition that contains the fields to update. This endpoint\nsupports sparse updates, so only new or changed fields need to be included in the request.\nOnly the following fields can be updated:\n\n- `name`\n- `description`\n- `visibility`\n- `schema` for a `Selection` data type. Only changes to the named options or the maximum number of allowed\nselections are supported.\n\nFor more information, see\n[Updatable definition fields](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attribute-definitions#updatable-definition-fields).\n\nTo enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) \ncontrol, include the optional `version` field and specify the current version of the custom attribute definition.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "The key of the custom attribute definition to update.", "readOnly": false, "required": true } ] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] } ], "BulkUpsertCustomerCustomAttributesRequest": [ { "name": "BulkUpsertCustomerCustomAttributesRequest", "properties": [ { "name": "values", "type": "map", "description": "A map containing 1 to 25 individual upsert requests. For each request, provide an\narbitrary ID that is unique for this `BulkUpsertCustomerCustomAttributes` request and the\ninformation needed to create or update a custom attribute.", "readOnly": false, "required": true } ] } ], "ListCustomerCustomAttributesRequest": [ { "name": "ListCustomerCustomAttributesRequest", "properties": [ { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request. For more\ninformation, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "with_definitions", "type": "boolean", "description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each\ncustom attribute. Set this parameter to `true` to get the name and description of each custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the target [customer profile](entity:Customer).", "readOnly": false, "required": true } ] } ], "DeleteCustomerCustomAttributeRequest": [ { "name": "DeleteCustomerCustomAttributeRequest", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the target [customer profile](entity:Customer).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to delete. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "RetrieveCustomerCustomAttributeRequest": [ { "name": "RetrieveCustomerCustomAttributeRequest", "properties": [ { "name": "with_definition", "type": "boolean", "description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of\nthe custom attribute. Set this parameter to `true` to get the name and description of the custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The current version of the custom attribute, which is used for strongly consistent reads to\nguarantee that you receive the most up-to-date data. When included in the request, Square\nreturns the specified version or a higher version if one exists. If the specified version is\nhigher than the current version, Square returns a `BAD_REQUEST` error.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the target [customer profile](entity:Customer).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to retrieve. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "UpsertCustomerCustomAttributeRequest": [ { "name": "UpsertCustomerCustomAttributeRequest", "properties": [ { "name": "custom_attribute", "type": "#/components/schemas/CustomAttribute", "description": "The custom attribute to create or update, with the following fields:\n\n- `value`. This value must conform to the `schema` specified by the definition. \nFor more information, see [Value data types](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attributes#value-data-types).\n\n- `version`. To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol for an update operation, include this optional field and specify the current version\nof the custom attribute.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the target [customer profile](entity:Customer).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to create or update. This key must match the `key` of a\ncustom attribute definition in the Square seller account. If the requesting application is not\nthe definition owner, you must use the qualified key.", "readOnly": false, "required": true } ] }, { "name": "CustomAttribute", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).", "readOnly": false, "required": false }, { "name": "value", "type": "string", "description": "The value assigned to the custom attribute. It is validated against the custom\nattribute definition's schema on write operations. For more information about custom\nattribute values,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute. This field is incremented when the custom attribute is changed.\nWhen updating an existing custom attribute value, you can provide this field\nand specify the current version of the custom attribute to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "A copy of the `visibility` field value for the associated custom attribute definition.\n", "readOnly": true, "required": false }, { "name": "definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "A copy of the associated custom attribute definition object. This field is only set when\nthe optional field is specified on the request.", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute was created or was most recently\nupdated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "ListCustomerGroupsRequest": [ { "name": "ListCustomerGroupsRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for your original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.\nIf the limit is less than 1 or greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 50.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] } ], "CreateCustomerGroupRequest": [ { "name": "CreateCustomerGroupRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "The idempotency key for the request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "group", "type": "#/components/schemas/CustomerGroup", "description": "The customer group to create.", "readOnly": false, "required": true } ] }, { "name": "CustomerGroup", "properties": [ { "name": "id", "type": "string", "description": "A unique Square-generated ID for the customer group.", "readOnly": true, "required": false }, { "name": "name", "type": "string", "description": "The name of the customer group.", "readOnly": false, "required": true }, { "name": "created_at", "type": "string", "description": "The timestamp when the customer group was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the customer group was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "DeleteCustomerGroupRequest": [ { "name": "DeleteCustomerGroupRequest", "properties": [ { "name": "group_id", "type": "string", "description": "The ID of the customer group to delete.", "readOnly": false, "required": true } ] } ], "RetrieveCustomerGroupRequest": [ { "name": "RetrieveCustomerGroupRequest", "properties": [ { "name": "group_id", "type": "string", "description": "The ID of the customer group to retrieve.", "readOnly": false, "required": true } ] } ], "UpdateCustomerGroupRequest": [ { "name": "UpdateCustomerGroupRequest", "properties": [ { "name": "group", "type": "#/components/schemas/CustomerGroup", "description": "The `CustomerGroup` object including all the updates you want to make.", "readOnly": false, "required": true }, { "name": "group_id", "type": "string", "description": "The ID of the customer group to update.", "readOnly": false, "required": true } ] }, { "name": "CustomerGroup", "properties": [ { "name": "id", "type": "string", "description": "A unique Square-generated ID for the customer group.", "readOnly": true, "required": false }, { "name": "name", "type": "string", "description": "The name of the customer group.", "readOnly": false, "required": true }, { "name": "created_at", "type": "string", "description": "The timestamp when the customer group was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the customer group was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "ListCustomerSegmentsRequest": [ { "name": "ListCustomerSegmentsRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by previous calls to `ListCustomerSegments`.\nThis cursor is used to retrieve the next set of query results.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.\nIf the specified limit is less than 1 or greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 50.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] } ], "RetrieveCustomerSegmentRequest": [ { "name": "RetrieveCustomerSegmentRequest", "properties": [ { "name": "segment_id", "type": "string", "description": "The Square-issued ID of the customer segment.", "readOnly": false, "required": true } ] } ], "ListCustomersRequest": [ { "name": "ListCustomersRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for your original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.\nIf the specified limit is less than 1 or greater than 100, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 100.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "sort_field", "type": "#/components/schemas/CustomerSortField", "description": "Indicates how customers should be sorted.\n\nThe default value is `DEFAULT`.\n", "readOnly": false, "required": false }, { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "Indicates whether customers should be sorted in ascending (`ASC`) or\ndescending (`DESC`) order.\n\nThe default value is `ASC`.\n", "readOnly": false, "required": false }, { "name": "count", "type": "boolean", "description": "Indicates whether to return the total count of customers in the `count` field of the response.\n\nThe default value is `false`.", "readOnly": false, "required": false } ] }, { "name": "CustomerSortField", "properties": [] }, { "name": "SortOrder", "properties": [] } ], "CreateCustomerRequest": [ { "name": "CreateCustomerRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "The idempotency key for the request.\tFor more information, see\n[Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "given_name", "type": "string", "description": "The given name (that is, the first name) associated with the customer profile.\n\nThe maximum length for this value is 300 characters.", "readOnly": false, "required": false }, { "name": "family_name", "type": "string", "description": "The family name (that is, the last name) associated with the customer profile.\n\nThe maximum length for this value is 300 characters.", "readOnly": false, "required": false }, { "name": "company_name", "type": "string", "description": "A business name associated with the customer profile.\n\nThe maximum length for this value is 500 characters.", "readOnly": false, "required": false }, { "name": "nickname", "type": "string", "description": "A nickname for the customer profile.\n\nThe maximum length for this value is 100 characters.", "readOnly": false, "required": false }, { "name": "email_address", "type": "string", "description": "The email address associated with the customer profile.\n\nThe maximum length for this value is 254 characters.", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The physical address associated with the customer profile. For maximum length constraints, see \n[Customer addresses](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#address).\nThe `first_name` and `last_name` fields are ignored if they are present in the request.", "readOnly": false, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number associated with the customer profile. The phone number must be valid and can contain\n9–16 digits, with an optional `+` prefix and country code. For more information, see\n[Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number).", "readOnly": false, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional second ID used to associate the customer profile with an\nentity in another system.\n\nThe maximum length for this value is 100 characters.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "A custom note associated with the customer profile.", "readOnly": false, "required": false }, { "name": "birthday", "type": "string", "description": "The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format. For example,\nspecify `1998-09-21` for September 21, 1998, or `09-21` for September 21. Birthdays are returned in `YYYY-MM-DD`\nformat, where `YYYY` is the specified birth year or `0000` if a birth year is not specified.", "readOnly": false, "required": false }, { "name": "tax_ids", "type": "#/components/schemas/CustomerTaxIds", "description": "The tax ID associated with the customer profile. This field is available only for customers of sellers\nin EU countries or the United Kingdom. For more information,\nsee [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).", "readOnly": false, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "CustomerTaxIds", "properties": [ { "name": "eu_vat", "type": "string", "description": "The EU VAT identification number for the customer. For example, `IE3426675K`. The ID can contain alphanumeric characters only.", "readOnly": false, "required": false } ] } ], "BulkCreateCustomersRequest": [ { "name": "BulkCreateCustomersRequest", "properties": [ { "name": "customers", "type": "map", "description": "A map of 1 to 100 individual create requests, represented by `idempotency key: { customer data }`\nkey-value pairs.\n\nEach key is an [idempotency key](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)\nthat uniquely identifies the create request. Each value contains the customer data used to create the\ncustomer profile.", "readOnly": false, "required": true } ] } ], "BulkDeleteCustomersRequest": [ { "name": "BulkDeleteCustomersRequest", "properties": [ { "name": "customer_ids", "type": "array", "description": "The IDs of the [customer profiles](entity:Customer) to delete.", "readOnly": false, "required": true } ] } ], "BulkRetrieveCustomersRequest": [ { "name": "BulkRetrieveCustomersRequest", "properties": [ { "name": "customer_ids", "type": "array", "description": "The IDs of the [customer profiles](entity:Customer) to retrieve.", "readOnly": false, "required": true } ] } ], "BulkUpdateCustomersRequest": [ { "name": "BulkUpdateCustomersRequest", "properties": [ { "name": "customers", "type": "map", "description": "A map of 1 to 100 individual update requests, represented by `customer ID: { customer data }`\nkey-value pairs.\n\nEach key is the ID of the [customer profile](entity:Customer) to update. To update a customer profile\nthat was created by merging existing profiles, provide the ID of the newly created profile.\n\nEach value contains the updated customer data. Only new or changed fields are required. To add or\nupdate a field, specify the new value. To remove a field, specify `null`.", "readOnly": false, "required": true } ] } ], "SearchCustomersRequest": [ { "name": "SearchCustomersRequest", "properties": [ { "name": "cursor", "type": "string", "description": "Include the pagination cursor in subsequent calls to this endpoint to retrieve\nthe next set of results associated with the original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.\nIf the specified limit is invalid, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 100.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "query", "type": "#/components/schemas/CustomerQuery", "description": "The filtering and sorting criteria for the search request. If a query is not specified,\nSquare returns all customer profiles ordered alphabetically by `given_name` and `family_name`.", "readOnly": false, "required": false }, { "name": "count", "type": "boolean", "description": "Indicates whether to return the total count of matching customers in the `count` field of the response.\n\nThe default value is `false`.", "readOnly": false, "required": false } ] }, { "name": "CustomerQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/CustomerFilter", "description": "The filtering criteria for the search query. A query can contain multiple filters in any combination.\nMultiple filters are combined as `AND` statements.\n\n__Note:__ Combining multiple filters as `OR` statements is not supported. Instead, send multiple single-filter\nsearches and join the result sets.", "readOnly": false, "required": false }, { "name": "sort", "type": "#/components/schemas/CustomerSort", "description": "Sorting criteria for query results. The default behavior is to sort \ncustomers alphabetically by `given_name` and `family_name`.", "readOnly": false, "required": false } ] }, { "name": "CustomerFilter", "properties": [ { "name": "creation_source", "type": "#/components/schemas/CustomerCreationSourceFilter", "description": "A filter to select customers based on their creation source.", "readOnly": false, "required": false }, { "name": "created_at", "type": "#/components/schemas/TimeRange", "description": "A filter to select customers based on when they were created.", "readOnly": false, "required": false }, { "name": "updated_at", "type": "#/components/schemas/TimeRange", "description": "A filter to select customers based on when they were last updated.", "readOnly": false, "required": false }, { "name": "email_address", "type": "#/components/schemas/CustomerTextFilter", "description": "A filter to [select customers by their email address](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-email-address) \nvisible to the seller. \nThis filter is case-insensitive.\n\nFor [exact matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#exact-search-by-email-address), this\nfilter causes the search to return customer profiles \nwhose `email_address` field value are identical to the email address provided\nin the query.\n\nFor [fuzzy matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#fuzzy-search-by-email-address), \nthis filter causes the search to return customer profiles \nwhose `email_address` field value has a token-wise partial match against the filtering \nexpression in the query. For example, with `Steven gmail` provided in a search\nquery, the search returns customers whose email address is `steven.johnson@gmail.com` \nor `mygmail@stevensbakery.com`. Square removes any punctuation (including periods (.),\nunderscores (_), and the @ symbol) and tokenizes the email addresses on spaces. A match is\nfound if a tokenized email address contains all the tokens in the search query, \nirrespective of the token order.", "readOnly": false, "required": false }, { "name": "phone_number", "type": "#/components/schemas/CustomerTextFilter", "description": "A filter to [select customers by their phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-phone-number)\nvisible to the seller.\n\nFor [exact matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#exact-search-by-phone-number),\nthis filter returns customers whose phone number matches the specified query expression. The number in the query must be of an\nE.164-compliant form. In particular, it must include the leading `+` sign followed by a country code and then a subscriber number.\nFor example, the standard E.164 form of a US phone number is `+12062223333` and an E.164-compliant variation is `+1 (206) 222-3333`.\nTo match the query expression, stored customer phone numbers are converted to the standard E.164 form.\n\nFor [fuzzy matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#fuzzy-search-by-phone-number),\nthis filter returns customers whose phone number matches the token or tokens provided in the query expression. For example, with `415`\nprovided in a search query, the search returns customers with the phone numbers `+1-415-212-1200`, `+1-212-415-1234`, and `+1 (551) 234-1567`.\nSimilarly, a search query of `415 123` returns customers with the phone numbers `+1-212-415-1234` and `+1 (551) 234-1567` but not\n`+1-212-415-1200`. A match is found if a tokenized phone number contains all the tokens in the search query, irrespective of the token order.", "readOnly": false, "required": false }, { "name": "reference_id", "type": "#/components/schemas/CustomerTextFilter", "description": "A filter to [select customers by their reference IDs](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-reference-id).\nThis filter is case-insensitive.\n\n[Exact matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#exact-search-by-reference-id) \nof a customer's reference ID against a query's reference ID is evaluated as an\nexact match between two strings, character by character in the given order.\n\n[Fuzzy matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#fuzzy-search-by-reference-id) \nof stored reference IDs against queried reference IDs works \nexactly the same as fuzzy matching on email addresses. Non-alphanumeric characters \nare replaced by spaces to tokenize stored and queried reference IDs. A match is found\nif a tokenized stored reference ID contains all tokens specified in any order in the query. For example,\na query of `NYC M` matches customer profiles with the `reference_id` value of `NYC_M_35_JOHNSON`\nand `NYC_27_MURRAY`.", "readOnly": false, "required": false }, { "name": "group_ids", "type": "#/components/schemas/FilterValue", "description": "A filter to select customers based on the [groups](entity:CustomerGroup) they belong to.\nGroup membership is controlled by sellers and developers.\n\nThe `group_ids` filter has the following syntax:\n```\n\"group_ids\": {\n\"any\": [\"{group_a_id}\", \"{group_b_id}\", ...],\n\"all\": [\"{group_1_id}\", \"{group_2_id}\", ...],\n\"none\": [\"{group_i_id}\", \"{group_ii_id}\", ...]\n}\n```\n\nYou can use any combination of the `any`, `all`, and `none` fields in the filter.\nWith `any`, the search returns customers in groups `a` or `b` or any other group specified in the list.\nWith `all`, the search returns customers in groups `1` and `2` and all other groups specified in the list.\nWith `none`, the search returns customers not in groups `i` or `ii` or any other group specified in the list.\n\nIf any of the search conditions are not met, including when an invalid or non-existent group ID is provided,\nthe result is an empty object (`{}`).", "readOnly": false, "required": false }, { "name": "custom_attribute", "type": "#/components/schemas/CustomerCustomAttributeFilters", "description": "A filter to select customers based on one or more custom attributes. \nThis filter can contain up to 10 custom attribute filters. Each custom attribute filter specifies filtering criteria for a target custom\nattribute. If multiple custom attribute filters are provided, they are combined as an `AND` operation.\n\nTo be valid for a search, the custom attributes must be visible to the requesting application. For more information, including example queries,\nsee [Search by custom attribute](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-custom-attribute).\n\nSquare returns matching customer profiles, which do not contain custom attributes. To retrieve customer-related custom attributes,\nuse the [Customer Custom Attributes API](api:CustomerCustomAttributes). For example, you can call\n[RetrieveCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-RetrieveCustomerCustomAttribute) using a customer ID from the result set.", "readOnly": false, "required": false }, { "name": "segment_ids", "type": "#/components/schemas/FilterValue", "description": " A filter to select customers based on the [segments](entity:CustomerSegment) they belong to.\nSegment membership is dynamic and adjusts automatically based on whether customers meet the segment criteria.\n\nYou can provide up to three segment IDs in the filter, using any combination of the `all`, `any`, and `none` fields.\nFor the following example, the results include customers who belong to both segment A and segment B but do not belong to segment C.\n\n```\n\"segment_ids\": {\n\"all\": [\"{segment_A_id}\", \"{segment_B_id}\"],\n\"none\": [\"{segment_C_id}\"]\n}\n```\n\nIf an invalid or non-existent segment ID is provided in the filter, Square stops processing the request\nand returns a `400 BAD_REQUEST` error that includes the segment ID.", "readOnly": false, "required": false } ] }, { "name": "CustomerCreationSourceFilter", "properties": [ { "name": "values", "type": "array", "description": "The list of creation sources used as filtering criteria.\n", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CustomerCreationSource" }, { "name": "rule", "type": "#/components/schemas/CustomerInclusionExclusion", "description": "Indicates whether a customer profile matching the filter criteria\nshould be included in the result or excluded from the result.\n\nDefault: `INCLUDE`.\n", "readOnly": false, "required": false } ] }, { "name": "CustomerCreationSource", "properties": [] }, { "name": "CustomerInclusionExclusion", "properties": [] }, { "name": "TimeRange", "properties": [ { "name": "start_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nstarts.", "readOnly": false, "required": false }, { "name": "end_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nends.", "readOnly": false, "required": false } ] }, { "name": "CustomerTextFilter", "properties": [ { "name": "exact", "type": "string", "description": "Use the exact filter to select customers whose attributes match exactly the specified query.", "readOnly": false, "required": false }, { "name": "fuzzy", "type": "string", "description": "Use the fuzzy filter to select customers whose attributes match the specified query \nin a fuzzy manner. When the fuzzy option is used, search queries are tokenized, and then \neach query token must be matched somewhere in the searched attribute. For single token queries, \nthis is effectively the same behavior as a partial match operation.", "readOnly": false, "required": false } ] }, { "name": "FilterValue", "properties": [ { "name": "all", "type": "array", "description": "A list of terms that must be present on the field of the resource.", "readOnly": false, "required": false }, { "name": "any", "type": "array", "description": "A list of terms where at least one of them must be present on the\nfield of the resource.", "readOnly": false, "required": false }, { "name": "none", "type": "array", "description": "A list of terms that must not be present on the field the resource", "readOnly": false, "required": false } ] }, { "name": "CustomerCustomAttributeFilters", "properties": [ { "name": "filters", "type": "array", "description": "The custom attribute filters. Each filter must specify `key` and include the `filter` field with a type-specific filter,\nthe `updated_at` field, or both. The provided keys must be unique within the list of custom attribute filters.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/CustomerCustomAttributeFilter" } ] }, { "name": "CustomerCustomAttributeFilter", "properties": [ { "name": "key", "type": "string", "description": "The `key` of the [custom attribute](entity:CustomAttribute) to filter by. The key is the identifier of the custom attribute\n(and the corresponding custom attribute definition) and can be retrieved using the [Customer Custom Attributes API](api:CustomerCustomAttributes).", "readOnly": false, "required": true }, { "name": "filter", "type": "#/components/schemas/CustomerCustomAttributeFilterValue", "description": "A filter that corresponds to the data type of the target custom attribute. For example, provide the `phone` filter to\nsearch based on the value of a `PhoneNumber`-type custom attribute. The data type is specified by the schema field of the custom attribute definition,\nwhich can be retrieved using the [Customer Custom Attributes API](api:CustomerCustomAttributes).\n\nYou must provide this `filter` field, the `updated_at` field, or both.", "readOnly": false, "required": false }, { "name": "updated_at", "type": "#/components/schemas/TimeRange", "description": "The date range for when the custom attribute was last updated. The date range can include `start_at`, `end_at`, or\nboth. Range boundaries are inclusive. Dates are specified as RFC 3339 timestamps.\n\nYou must provide this `updated_at` field, the `filter` field, or both.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false } ] }, { "name": "CustomerCustomAttributeFilterValue", "properties": [ { "name": "email", "type": "#/components/schemas/CustomerTextFilter", "description": "A filter for a query based on the value of an `Email`-type custom attribute. This filter is case-insensitive and can\ninclude `exact` or `fuzzy`, but not both.\n\nFor an `exact` match, provide the complete email address.\n\nFor a `fuzzy` match, provide a query expression containing one or more query tokens to match against the email address. Square removes\nany punctuation (including periods (.), underscores (_), and the @ symbol) and tokenizes the email addresses on spaces. A match is found\nif a tokenized email address contains all the tokens in the search query, irrespective of the token order. For example, `Steven gmail`\nmatches steven.jones@gmail.com and mygmail@stevensbakery.com.", "readOnly": false, "required": false }, { "name": "phone", "type": "#/components/schemas/CustomerTextFilter", "description": "A filter for a query based on the value of a `PhoneNumber`-type custom attribute. This filter is case-insensitive and\ncan include `exact` or `fuzzy`, but not both.\n\nFor an `exact` match, provide the complete phone number. This is always an E.164-compliant phone number that starts\nwith the + sign followed by the country code and subscriber number. For example, the format for a US phone number is +12061112222.\n\nFor a `fuzzy` match, provide a query expression containing one or more query tokens to match against the phone number.\nSquare removes any punctuation and tokenizes the expression on spaces. A match is found if a tokenized phone number contains\nall the tokens in the search query, irrespective of the token order. For example, `415 123 45` is tokenized to `415`, `123`, and `45`,\nwhich matches +14151234567 and +12345674158, but does not match +1234156780. Similarly, the expression `415` matches\n+14151234567, +12345674158, and +1234156780.", "readOnly": false, "required": false }, { "name": "text", "type": "#/components/schemas/CustomerTextFilter", "description": "A filter for a query based on the value of a `String`-type custom attribute. This filter is case-insensitive and \ncan include `exact` or `fuzzy`, but not both.\n\nFor an `exact` match, provide the complete string.\n\nFor a `fuzzy` match, provide a query expression containing one or more query tokens in any order that contain complete words\nto match against the string. Square tokenizes the expression using a grammar-based tokenizer. For example, the expressions `quick brown`,\n`brown quick`, and `quick fox` match \"The quick brown fox jumps over the lazy dog\". However, `quick foxes` and `qui` do not match.", "readOnly": false, "required": false }, { "name": "selection", "type": "#/components/schemas/FilterValue", "description": "A filter for a query based on the display name for a `Selection`-type custom attribute value. This filter is case-sensitive\nand can contain `any`, `all`, or both. The `none` condition is not supported.\n\nProvide the display name of each item that you want to search for. To find the display names for the selection, use the \n[Customer Custom Attributes API](api:CustomerCustomAttributes) to retrieve the corresponding custom attribute definition\nand then check the `schema.items.names` field. For more information, see\n[Search based on selection](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#custom-attribute-value-filter-selection).\n\nNote that when a `Selection`-type custom attribute is assigned to a customer profile, the custom attribute value is a list of one\nor more UUIDs (sourced from the `schema.items.enum` field) that map to the item names. These UUIDs are unique per seller.", "readOnly": false, "required": false }, { "name": "date", "type": "#/components/schemas/TimeRange", "description": "A filter for a query based on the value of a `Date`-type custom attribute.\n\nProvide a date range for this filter using `start_at`, `end_at`, or both. Range boundaries are inclusive. Dates can be specified\nin `YYYY-MM-DD` format or as RFC 3339 timestamps.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "number", "type": "#/components/schemas/FloatNumberRange", "description": "A filter for a query based on the value of a `Number`-type custom attribute, which can be an integer or a decimal with up to\n5 digits of precision.\n\nProvide a numerical range for this filter using `start_at`, `end_at`, or both. Range boundaries are inclusive. Numbers are specified\nas decimals or integers. The absolute value of range boundaries must not exceed `(2^63-1)/10^5`, or 92233720368547.", "readOnly": false, "required": false }, { "name": "boolean", "type": "boolean", "description": "A filter for a query based on the value of a `Boolean`-type custom attribute.", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/CustomerAddressFilter", "description": "A filter for a query based on the value of an `Address`-type custom attribute. The filter can include `postal_code`, `country`, or both.", "readOnly": false, "required": false } ] }, { "name": "FloatNumberRange", "properties": [ { "name": "start_at", "type": "string", "description": "A decimal value indicating where the range starts.", "readOnly": false, "required": false }, { "name": "end_at", "type": "string", "description": "A decimal value indicating where the range ends.", "readOnly": false, "required": false } ] }, { "name": "CustomerAddressFilter", "properties": [ { "name": "postal_code", "type": "#/components/schemas/CustomerTextFilter", "description": "The postal code to search for. Only an `exact` match is supported.", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The country code to search for.\n", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "CustomerSort", "properties": [ { "name": "field", "type": "#/components/schemas/CustomerSortField", "description": "Indicates the fields to use as the sort key, which is either the default set of fields or `created_at`.\n\nThe default value is `DEFAULT`.\n", "readOnly": false, "required": false }, { "name": "order", "type": "#/components/schemas/SortOrder", "description": "Indicates the order in which results should be sorted based on the\nsort field value. Strings use standard alphabetic comparison\nto determine order. Strings representing numbers are sorted as strings.\n\nThe default value is `ASC`.\n", "readOnly": false, "required": false } ] }, { "name": "CustomerSortField", "properties": [] }, { "name": "SortOrder", "properties": [] } ], "DeleteCustomerRequest": [ { "name": "DeleteCustomerRequest", "properties": [ { "name": "version", "type": "integer", "description": "The current version of the customer profile.\n\nAs a best practice, you should include this parameter to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Delete a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile).", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the customer to delete.", "readOnly": false, "required": true } ] } ], "RetrieveCustomerRequest": [ { "name": "RetrieveCustomerRequest", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer to retrieve.", "readOnly": false, "required": true } ] } ], "UpdateCustomerRequest": [ { "name": "UpdateCustomerRequest", "properties": [ { "name": "given_name", "type": "string", "description": "The given name (that is, the first name) associated with the customer profile.\n\nThe maximum length for this value is 300 characters.", "readOnly": false, "required": false }, { "name": "family_name", "type": "string", "description": "The family name (that is, the last name) associated with the customer profile.\n\nThe maximum length for this value is 300 characters.", "readOnly": false, "required": false }, { "name": "company_name", "type": "string", "description": "A business name associated with the customer profile.\n\nThe maximum length for this value is 500 characters.", "readOnly": false, "required": false }, { "name": "nickname", "type": "string", "description": "A nickname for the customer profile.\n\nThe maximum length for this value is 100 characters.", "readOnly": false, "required": false }, { "name": "email_address", "type": "string", "description": "The email address associated with the customer profile.\n\nThe maximum length for this value is 254 characters.", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The physical address associated with the customer profile. Only new or changed fields are required in the request.\n\nFor maximum length constraints, see [Customer addresses](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#address).\nThe `first_name` and `last_name` fields are ignored if they are present in the request.", "readOnly": false, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number associated with the customer profile. The phone number must be valid and can contain\n9–16 digits, with an optional `+` prefix and country code. For more information, see\n[Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number).", "readOnly": false, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional second ID used to associate the customer profile with an\nentity in another system.\n\nThe maximum length for this value is 100 characters.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "A custom note associated with the customer profile.", "readOnly": false, "required": false }, { "name": "birthday", "type": "string", "description": "The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format. For example,\nspecify `1998-09-21` for September 21, 1998, or `09-21` for September 21. Birthdays are returned in `YYYY-MM-DD`\nformat, where `YYYY` is the specified birth year or `0000` if a birth year is not specified.", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The current version of the customer profile.\n\nAs a best practice, you should include this field to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Update a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#update-a-customer-profile).", "readOnly": false, "required": false }, { "name": "tax_ids", "type": "#/components/schemas/CustomerTaxIds", "description": "The tax ID associated with the customer profile. This field is available only for customers of sellers\nin EU countries or the United Kingdom. For more information,\nsee [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the customer to update.", "readOnly": false, "required": true } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "CustomerTaxIds", "properties": [ { "name": "eu_vat", "type": "string", "description": "The EU VAT identification number for the customer. For example, `IE3426675K`. The ID can contain alphanumeric characters only.", "readOnly": false, "required": false } ] } ], "RemoveGroupFromCustomerRequest": [ { "name": "RemoveGroupFromCustomerRequest", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer to remove from the group.", "readOnly": false, "required": true }, { "name": "group_id", "type": "string", "description": "The ID of the customer group to remove the customer from.", "readOnly": false, "required": true } ] } ], "AddGroupToCustomerRequest": [ { "name": "AddGroupToCustomerRequest", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer to add to a group.", "readOnly": false, "required": true }, { "name": "group_id", "type": "string", "description": "The ID of the customer group to add the customer to.", "readOnly": false, "required": true } ] } ], "ListDevicesRequest": [ { "name": "ListDevicesRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\nSee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.", "readOnly": false, "required": false }, { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "The order in which results are listed.\n- `ASC` - Oldest to newest.\n- `DESC` - Newest to oldest (default).\n", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The number of results to return in a single page.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "If present, only returns devices at the target location.", "readOnly": false, "required": false } ] }, { "name": "SortOrder", "properties": [] } ], "ListDeviceCodesRequest": [ { "name": "ListDeviceCodesRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for your original query.\n\nSee [Paginating results](https://developer.squareup.com/docs/working-with-apis/pagination) for more information.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "If specified, only returns DeviceCodes of the specified location.\nReturns DeviceCodes of all locations if empty.", "readOnly": false, "required": false }, { "name": "product_type", "type": "#/components/schemas/ProductType", "description": "If specified, only returns DeviceCodes targeting the specified product type.\nReturns DeviceCodes of all product types if empty.", "readOnly": false, "required": false }, { "name": "status", "type": "array", "description": "If specified, returns DeviceCodes with the specified statuses.\nReturns DeviceCodes of status `PAIRED` and `UNPAIRED` if empty.\n", "readOnly": false, "required": false, "arrayType": "#/components/schemas/DeviceCodeStatus" } ] }, { "name": "ProductType", "properties": [] }, { "name": "DeviceCodeStatus", "properties": [] } ], "CreateDeviceCodeRequest": [ { "name": "CreateDeviceCodeRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this CreateDeviceCode request. Keys can\nbe any valid string but must be unique for every CreateDeviceCode request.\n\nSee [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information.", "readOnly": false, "required": true }, { "name": "device_code", "type": "#/components/schemas/DeviceCode", "description": "The device code to create.", "readOnly": false, "required": true } ] }, { "name": "DeviceCode", "properties": [ { "name": "id", "type": "string", "description": "The unique id for this device code.", "readOnly": true, "required": false }, { "name": "name", "type": "string", "description": "An optional user-defined name for the device code.", "readOnly": false, "required": false }, { "name": "code", "type": "string", "description": "The unique code that can be used to login.", "readOnly": true, "required": false }, { "name": "device_id", "type": "string", "description": "The unique id of the device that used this code. Populated when the device is paired up.", "readOnly": true, "required": false }, { "name": "product_type", "type": "#/components/schemas/ProductType", "description": "The targeting product type of the device code.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The location assigned to this code.", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/DeviceCodeStatus", "description": "The pairing status of the device code.\n", "readOnly": true, "required": false }, { "name": "pair_by", "type": "string", "description": "When this DeviceCode will expire and no longer login. Timestamp in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "When this DeviceCode was created. Timestamp in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "status_changed_at", "type": "string", "description": "When this DeviceCode's status was last changed. Timestamp in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "paired_at", "type": "string", "description": "When this DeviceCode was paired. Timestamp in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "ProductType", "properties": [] }, { "name": "DeviceCodeStatus", "properties": [] } ], "GetDeviceCodeRequest": [ { "name": "GetDeviceCodeRequest", "properties": [ { "name": "id", "type": "string", "description": "The unique identifier for the device code.", "readOnly": false, "required": true } ] } ], "GetDeviceRequest": [ { "name": "GetDeviceRequest", "properties": [ { "name": "device_id", "type": "string", "description": "The unique ID for the desired `Device`.", "readOnly": false, "required": true } ] } ], "ListDisputesRequest": [ { "name": "ListDisputesRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "states", "type": "array", "description": "The dispute states used to filter the result. If not specified, the endpoint returns all disputes.\n", "readOnly": false, "required": false, "arrayType": "#/components/schemas/DisputeState" }, { "name": "location_id", "type": "string", "description": "The ID of the location for which to return a list of disputes.\nIf not specified, the endpoint returns disputes associated with all locations.", "readOnly": false, "required": false } ] }, { "name": "DisputeState", "properties": [] } ], "RetrieveDisputeRequest": [ { "name": "RetrieveDisputeRequest", "properties": [ { "name": "dispute_id", "type": "string", "description": "The ID of the dispute you want more details about.", "readOnly": false, "required": true } ] } ], "AcceptDisputeRequest": [ { "name": "AcceptDisputeRequest", "properties": [ { "name": "dispute_id", "type": "string", "description": "The ID of the dispute you want to accept.", "readOnly": false, "required": true } ] } ], "ListDisputeEvidenceRequest": [ { "name": "ListDisputeEvidenceRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "dispute_id", "type": "string", "description": "The ID of the dispute.", "readOnly": false, "required": true } ] } ], "CreateDisputeEvidenceFileRequest": [ { "name": "CreateDisputeEvidenceFileRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique key identifying the request. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).", "readOnly": false, "required": true }, { "name": "evidence_type", "type": "#/components/schemas/DisputeEvidenceType", "description": "The type of evidence you are uploading.\n", "readOnly": false, "required": false }, { "name": "content_type", "type": "string", "description": "The MIME type of the uploaded file.\nThe type can be image/heic, image/heif, image/jpeg, application/pdf, image/png, or image/tiff.", "readOnly": false, "required": false }, { "name": "dispute_id", "type": "string", "description": "The ID of the dispute for which you want to upload evidence.", "readOnly": false, "required": true } ] }, { "name": "DisputeEvidenceType", "properties": [] } ], "CreateDisputeEvidenceTextRequest": [ { "name": "CreateDisputeEvidenceTextRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique key identifying the request. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).", "readOnly": false, "required": true }, { "name": "evidence_type", "type": "#/components/schemas/DisputeEvidenceType", "description": "The type of evidence you are uploading.\n", "readOnly": false, "required": false }, { "name": "evidence_text", "type": "string", "description": "The evidence string.", "readOnly": false, "required": true }, { "name": "dispute_id", "type": "string", "description": "The ID of the dispute for which you want to upload evidence.", "readOnly": false, "required": true } ] }, { "name": "DisputeEvidenceType", "properties": [] } ], "DeleteDisputeEvidenceRequest": [ { "name": "DeleteDisputeEvidenceRequest", "properties": [ { "name": "dispute_id", "type": "string", "description": "The ID of the dispute from which you want to remove evidence.", "readOnly": false, "required": true }, { "name": "evidence_id", "type": "string", "description": "The ID of the evidence you want to remove.", "readOnly": false, "required": true } ] } ], "RetrieveDisputeEvidenceRequest": [ { "name": "RetrieveDisputeEvidenceRequest", "properties": [ { "name": "dispute_id", "type": "string", "description": "The ID of the dispute from which you want to retrieve evidence metadata.", "readOnly": false, "required": true }, { "name": "evidence_id", "type": "string", "description": "The ID of the evidence to retrieve.", "readOnly": false, "required": true } ] } ], "SubmitEvidenceRequest": [ { "name": "SubmitEvidenceRequest", "properties": [ { "name": "dispute_id", "type": "string", "description": "The ID of the dispute for which you want to submit evidence.", "readOnly": false, "required": true } ] } ], "SearchEventsRequest": [ { "name": "SearchEventsRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of events for your original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of events to return in a single page. The response might contain fewer events. The default value is 100, which is also the maximum allowed value.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).\n\nDefault: 100", "readOnly": false, "required": false }, { "name": "query", "type": "#/components/schemas/SearchEventsQuery", "description": "The filtering and sorting criteria for the search request. To retrieve additional pages using a cursor, you must use the original query.", "readOnly": false, "required": false } ] }, { "name": "SearchEventsQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/SearchEventsFilter", "description": "Criteria to filter events by.", "readOnly": false, "required": false }, { "name": "sort", "type": "#/components/schemas/SearchEventsSort", "description": "Criteria to sort events by.", "readOnly": false, "required": false } ] }, { "name": "SearchEventsFilter", "properties": [ { "name": "event_types", "type": "array", "description": "Filter events by event types.", "readOnly": false, "required": false }, { "name": "merchant_ids", "type": "array", "description": "Filter events by merchant.", "readOnly": false, "required": false }, { "name": "location_ids", "type": "array", "description": "Filter events by location.", "readOnly": false, "required": false }, { "name": "created_at", "type": "#/components/schemas/TimeRange", "description": "Filter events by when they were created.", "readOnly": false, "required": false } ] }, { "name": "TimeRange", "properties": [ { "name": "start_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nstarts.", "readOnly": false, "required": false }, { "name": "end_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nends.", "readOnly": false, "required": false } ] }, { "name": "SearchEventsSort", "properties": [ { "name": "field", "type": "#/components/schemas/SearchEventsSortField", "description": "Sort events by event types.\n", "readOnly": false, "required": false }, { "name": "order", "type": "#/components/schemas/SortOrder", "description": "The order to use for sorting the events.\n", "readOnly": false, "required": false } ] }, { "name": "SearchEventsSortField", "properties": [] }, { "name": "SortOrder", "properties": [] } ], "DisableEventsRequest": [ { "name": "DisableEventsRequest", "properties": [] } ], "EnableEventsRequest": [ { "name": "EnableEventsRequest", "properties": [] } ], "ListEventTypesRequest": [ { "name": "ListEventTypesRequest", "properties": [ { "name": "api_version", "type": "string", "description": "The API version for which to list event types. Setting this field overrides the default version used by the application.", "readOnly": false, "required": false } ] } ], "ListGiftCardActivitiesRequest": [ { "name": "ListGiftCardActivitiesRequest", "properties": [ { "name": "gift_card_id", "type": "string", "description": "If a gift card ID is provided, the endpoint returns activities related \nto the specified gift card. Otherwise, the endpoint returns all gift card activities for \nthe seller.", "readOnly": false, "required": false }, { "name": "type", "type": "string", "description": "If a [type](entity:GiftCardActivityType) is provided, the endpoint returns gift card activities of the specified type. \nOtherwise, the endpoint returns all types of gift card activities.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "If a location ID is provided, the endpoint returns gift card activities for the specified location. \nOtherwise, the endpoint returns gift card activities for all locations.", "readOnly": false, "required": false }, { "name": "begin_time", "type": "string", "description": "The timestamp for the beginning of the reporting period, in RFC 3339 format.\nThis start time is inclusive. The default value is the current time minus one year.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "end_time", "type": "string", "description": "The timestamp for the end of the reporting period, in RFC 3339 format.\nThis end time is inclusive. The default value is the current time.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "If a limit is provided, the endpoint returns the specified number \nof results (or fewer) per page. The maximum value is 100. The default value is 50.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\nIf a cursor is not provided, the endpoint returns the first page of the results.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "readOnly": false, "required": false }, { "name": "sort_order", "type": "string", "description": "The order in which the endpoint returns the activities, based on `created_at`.\n- `ASC` - Oldest to newest.\n- `DESC` - Newest to oldest (default).", "readOnly": false, "required": false } ] } ], "CreateGiftCardActivityRequest": [ { "name": "CreateGiftCardActivityRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies the `CreateGiftCardActivity` request.", "readOnly": false, "required": true }, { "name": "gift_card_activity", "type": "#/components/schemas/GiftCardActivity", "description": "The activity to create for the gift card. This activity must specify `gift_card_id` or `gift_card_gan` for the target\ngift card, the `location_id` where the activity occurred, and the activity `type` along with the corresponding activity details.", "readOnly": false, "required": true } ] }, { "name": "GiftCardActivity", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the gift card activity.", "readOnly": true, "required": false }, { "name": "type", "type": "#/components/schemas/GiftCardActivityType", "description": "The type of gift card activity.\n", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The ID of the [business location](entity:Location) where the activity occurred.", "readOnly": false, "required": true }, { "name": "created_at", "type": "string", "description": "The timestamp when the gift card activity was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "gift_card_id", "type": "string", "description": "The gift card ID. When creating a gift card activity, `gift_card_id` is not required if \n`gift_card_gan` is specified.", "readOnly": false, "required": false }, { "name": "gift_card_gan", "type": "string", "description": "The gift card account number (GAN). When creating a gift card activity, `gift_card_gan` \nis not required if `gift_card_id` is specified.", "readOnly": false, "required": false }, { "name": "gift_card_balance_money", "type": "#/components/schemas/Money", "description": "The final balance on the gift card after the action is completed.", "readOnly": true, "required": false }, { "name": "load_activity_details", "type": "#/components/schemas/GiftCardActivityLoad", "description": "Additional details about a `LOAD` activity, which is used to reload money onto a gift card.", "readOnly": false, "required": false }, { "name": "activate_activity_details", "type": "#/components/schemas/GiftCardActivityActivate", "description": "Additional details about an `ACTIVATE` activity, which is used to activate a gift card with \nan initial balance.", "readOnly": false, "required": false }, { "name": "redeem_activity_details", "type": "#/components/schemas/GiftCardActivityRedeem", "description": "Additional details about a `REDEEM` activity, which is used to redeem a gift card for a purchase.\n\nFor applications that process payments using the Square Payments API, Square creates a `REDEEM` activity that \nupdates the gift card balance after the corresponding [CreatePayment](api-endpoint:Payments-CreatePayment) \nrequest is completed. Applications that use a custom payment processing system must call \n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) to create the `REDEEM` activity.", "readOnly": false, "required": false }, { "name": "clear_balance_activity_details", "type": "#/components/schemas/GiftCardActivityClearBalance", "description": "Additional details about a `CLEAR_BALANCE` activity, which is used to set the balance of a gift card to zero.", "readOnly": false, "required": false }, { "name": "deactivate_activity_details", "type": "#/components/schemas/GiftCardActivityDeactivate", "description": "Additional details about a `DEACTIVATE` activity, which is used to deactivate a gift card.", "readOnly": false, "required": false }, { "name": "adjust_increment_activity_details", "type": "#/components/schemas/GiftCardActivityAdjustIncrement", "description": "Additional details about an `ADJUST_INCREMENT` activity, which is used to add money to a gift card \noutside of a typical `ACTIVATE`, `LOAD`, or `REFUND` activity flow.", "readOnly": false, "required": false }, { "name": "adjust_decrement_activity_details", "type": "#/components/schemas/GiftCardActivityAdjustDecrement", "description": "Additional details about an `ADJUST_DECREMENT` activity, which is used to deduct money from a gift \ncard outside of a typical `REDEEM` activity flow.", "readOnly": false, "required": false }, { "name": "refund_activity_details", "type": "#/components/schemas/GiftCardActivityRefund", "description": "Additional details about a `REFUND` activity, which is used to add money to a gift card when \nrefunding a payment.\n\nFor applications that refund payments to a gift card using the Square Refunds API, Square automatically\ncreates a `REFUND` activity that updates the gift card balance after a [RefundPayment](api-endpoint:Refunds-RefundPayment)\nrequest is completed. Applications that use a custom processing system must call\n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) to create the `REFUND` activity.", "readOnly": false, "required": false }, { "name": "unlinked_activity_refund_activity_details", "type": "#/components/schemas/GiftCardActivityUnlinkedActivityRefund", "description": "Additional details about an `UNLINKED_ACTIVITY_REFUND` activity. This activity is used to add money \nto a gift card when refunding a payment that was processed using a custom payment processing system\nand not linked to the gift card.", "readOnly": false, "required": false }, { "name": "import_activity_details", "type": "#/components/schemas/GiftCardActivityImport", "description": "Additional details about an `IMPORT` activity, which Square uses to import a third-party \ngift card with a balance.", "readOnly": true, "required": false }, { "name": "block_activity_details", "type": "#/components/schemas/GiftCardActivityBlock", "description": "Additional details about a `BLOCK` activity, which Square uses to temporarily block a gift card.", "readOnly": true, "required": false }, { "name": "unblock_activity_details", "type": "#/components/schemas/GiftCardActivityUnblock", "description": "Additional details about an `UNBLOCK` activity, which Square uses to unblock a gift card.", "readOnly": true, "required": false }, { "name": "import_reversal_activity_details", "type": "#/components/schemas/GiftCardActivityImportReversal", "description": "Additional details about an `IMPORT_REVERSAL` activity, which Square uses to reverse the \nimport of a third-party gift card.", "readOnly": true, "required": false }, { "name": "transfer_balance_to_activity_details", "type": "#/components/schemas/GiftCardActivityTransferBalanceTo", "description": "Additional details about a `TRANSFER_BALANCE_TO` activity, which Square uses to add money to\na gift card as the result of a transfer from another gift card.", "readOnly": true, "required": false }, { "name": "transfer_balance_from_activity_details", "type": "#/components/schemas/GiftCardActivityTransferBalanceFrom", "description": "Additional details about a `TRANSFER_BALANCE_FROM` activity, which Square uses to deduct money from\na gift as the result of a transfer to another gift card.", "readOnly": true, "required": false } ] }, { "name": "GiftCardActivityType", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "GiftCardActivityLoad", "properties": [ { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount added to the gift card. This value is a positive integer.\n\nApplications that use a custom order processing system must specify this amount in the \n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.\n\nApplications that use the Square Orders API to process orders must specify the order ID in the \n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.", "readOnly": false, "required": false }, { "name": "line_item_uid", "type": "string", "description": "The UID of the `GIFT_CARD` line item in the order that represents the additional funds for the gift card.\n\nApplications that use the Square Orders API to process orders must specify the line item UID\nin the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.", "readOnly": false, "required": false }, { "name": "reference_id", "type": "string", "description": "A client-specified ID that associates the gift card activity with an entity in another system. \n\nApplications that use a custom order processing system can use this field to track information related to \nan order or payment.", "readOnly": false, "required": false }, { "name": "buyer_payment_instrument_ids", "type": "array", "description": "The payment instrument IDs used to process the order for the additional funds, such as a credit card ID \nor bank account ID. \n\nApplications that use a custom order processing system must specify payment instrument IDs in \nthe [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.\nSquare uses this information to perform compliance checks. \n\nFor applications that use the Square Orders API to process payments, Square has the necessary \ninstrument IDs to perform compliance checks.\n\nEach buyer payment instrument ID can contain a maximum of 255 characters.", "readOnly": false, "required": false } ] }, { "name": "GiftCardActivityActivate", "properties": [ { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount added to the gift card. This value is a positive integer.\n\nApplications that use a custom order processing system must specify this amount in the \n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.\n\nApplications that use the Square Orders API to process orders must specify the order ID\n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.", "readOnly": false, "required": false }, { "name": "line_item_uid", "type": "string", "description": "The UID of the `GIFT_CARD` line item in the order that represents the gift card purchase.\n\nApplications that use the Square Orders API to process orders must specify the line item UID\nin the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.", "readOnly": false, "required": false }, { "name": "reference_id", "type": "string", "description": "A client-specified ID that associates the gift card activity with an entity in another system. \n\nApplications that use a custom order processing system can use this field to track information \nrelated to an order or payment.", "readOnly": false, "required": false }, { "name": "buyer_payment_instrument_ids", "type": "array", "description": "The payment instrument IDs used to process the gift card purchase, such as a credit card ID \nor bank account ID. \n\nApplications that use a custom order processing system must specify payment instrument IDs in \nthe [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.\nSquare uses this information to perform compliance checks. \n\nFor applications that use the Square Orders API to process payments, Square has the necessary \ninstrument IDs to perform compliance checks.\n\nEach buyer payment instrument ID can contain a maximum of 255 characters.", "readOnly": false, "required": false } ] }, { "name": "GiftCardActivityRedeem", "properties": [ { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount deducted from the gift card for the redemption. This value is a positive integer.\n\nApplications that use a custom payment processing system must specify this amount in the \n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.", "readOnly": false, "required": true }, { "name": "payment_id", "type": "string", "description": "The ID of the payment that represents the gift card redemption. Square populates this field \nif the payment was processed by Square.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "A client-specified ID that associates the gift card activity with an entity in another system. \n\nApplications that use a custom payment processing system can use this field to track information\nrelated to an order or payment.", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/GiftCardActivityRedeemStatus", "description": "The status of the gift card redemption. Gift cards redeemed from Square Point of Sale or the \nSquare Seller Dashboard use a two-state process: `PENDING` \nto `COMPLETED` or `PENDING` to `CANCELED`. Gift cards redeemed using the Gift Card Activities API \nalways have a `COMPLETED` status.\n", "readOnly": true, "required": false } ] }, { "name": "GiftCardActivityRedeemStatus", "properties": [] }, { "name": "GiftCardActivityClearBalance", "properties": [ { "name": "reason", "type": "#/components/schemas/GiftCardActivityClearBalanceReason", "description": "The reason the gift card balance was cleared.\n", "readOnly": false, "required": true } ] }, { "name": "GiftCardActivityClearBalanceReason", "properties": [] }, { "name": "GiftCardActivityDeactivate", "properties": [ { "name": "reason", "type": "#/components/schemas/GiftCardActivityDeactivateReason", "description": "The reason the gift card was deactivated.\n", "readOnly": false, "required": true } ] }, { "name": "GiftCardActivityDeactivateReason", "properties": [] }, { "name": "GiftCardActivityAdjustIncrement", "properties": [ { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount added to the gift card balance. This value is a positive integer.", "readOnly": false, "required": true }, { "name": "reason", "type": "#/components/schemas/GiftCardActivityAdjustIncrementReason", "description": "The reason the gift card balance was adjusted.\n", "readOnly": false, "required": true } ] }, { "name": "GiftCardActivityAdjustIncrementReason", "properties": [] }, { "name": "GiftCardActivityAdjustDecrement", "properties": [ { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount deducted from the gift card balance. This value is a positive integer.", "readOnly": false, "required": true }, { "name": "reason", "type": "#/components/schemas/GiftCardActivityAdjustDecrementReason", "description": "The reason the gift card balance was adjusted.\n", "readOnly": false, "required": true } ] }, { "name": "GiftCardActivityAdjustDecrementReason", "properties": [] }, { "name": "GiftCardActivityRefund", "properties": [ { "name": "redeem_activity_id", "type": "string", "description": "The ID of the refunded `REDEEM` gift card activity. Square populates this field if the \n`payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request \nrepresents a gift card redemption.\n\nFor applications that use a custom payment processing system, this field is required when creating\na `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount added to the gift card for the refund. This value is a positive integer.\n\nThis field is required when creating a `REFUND` activity. The amount can represent a full or partial refund.", "readOnly": false, "required": false }, { "name": "reference_id", "type": "string", "description": "A client-specified ID that associates the gift card activity with an entity in another system.", "readOnly": false, "required": false }, { "name": "payment_id", "type": "string", "description": "The ID of the refunded payment. Square populates this field if the refund is for a \npayment processed by Square. This field matches the `payment_id` in the corresponding\n[RefundPayment](api-endpoint:Refunds-RefundPayment) request.", "readOnly": true, "required": false } ] }, { "name": "GiftCardActivityUnlinkedActivityRefund", "properties": [ { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount added to the gift card for the refund. This value is a positive integer.", "readOnly": false, "required": true }, { "name": "reference_id", "type": "string", "description": "A client-specified ID that associates the gift card activity with an entity in another system.", "readOnly": false, "required": false }, { "name": "payment_id", "type": "string", "description": "The ID of the refunded payment. This field is not used starting in Square version 2022-06-16.", "readOnly": true, "required": false } ] }, { "name": "GiftCardActivityImport", "properties": [ { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The balance amount on the imported gift card.", "readOnly": false, "required": true } ] }, { "name": "GiftCardActivityBlock", "properties": [ { "name": "reason", "type": "#/components/schemas/GiftCardActivityBlockReason", "description": "The reason the gift card was blocked.\n", "readOnly": false, "required": true } ] }, { "name": "GiftCardActivityBlockReason", "properties": [] }, { "name": "GiftCardActivityUnblock", "properties": [ { "name": "reason", "type": "#/components/schemas/GiftCardActivityUnblockReason", "description": "The reason the gift card was unblocked.\n", "readOnly": false, "required": true } ] }, { "name": "GiftCardActivityUnblockReason", "properties": [] }, { "name": "GiftCardActivityImportReversal", "properties": [ { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money cleared from the third-party gift card when \nthe import was reversed.", "readOnly": false, "required": true } ] }, { "name": "GiftCardActivityTransferBalanceTo", "properties": [ { "name": "transfer_from_gift_card_id", "type": "string", "description": "The ID of the gift card from which the specified amount was transferred.", "readOnly": false, "required": true }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount added to the gift card balance for the transfer. This value is a positive integer.", "readOnly": false, "required": true } ] }, { "name": "GiftCardActivityTransferBalanceFrom", "properties": [ { "name": "transfer_to_gift_card_id", "type": "string", "description": "The ID of the gift card to which the specified amount was transferred.", "readOnly": false, "required": true }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount deducted from the gift card for the transfer. This value is a positive integer.", "readOnly": false, "required": true } ] } ], "ListGiftCardsRequest": [ { "name": "ListGiftCardsRequest", "properties": [ { "name": "type", "type": "string", "description": "If a [type](entity:GiftCardType) is provided, the endpoint returns gift cards of the specified type.\nOtherwise, the endpoint returns gift cards of all types.", "readOnly": false, "required": false }, { "name": "state", "type": "string", "description": "If a [state](entity:GiftCardStatus) is provided, the endpoint returns the gift cards in the specified state.\nOtherwise, the endpoint returns the gift cards of all states.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "If a limit is provided, the endpoint returns only the specified number of results per page.\nThe maximum value is 200. The default value is 30.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\nIf a cursor is not provided, the endpoint returns the first page of the results. \nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.", "readOnly": false, "required": false } ] } ], "CreateGiftCardRequest": [ { "name": "CreateGiftCardRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information, \nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The ID of the [location](entity:Location) where the gift card should be registered for \nreporting purposes. Gift cards can be redeemed at any of the seller's locations.", "readOnly": false, "required": true }, { "name": "gift_card", "type": "#/components/schemas/GiftCard", "description": "The gift card to create. The `type` field is required for this request. The `gan_source` \nand `gan` fields are included as follows: \n\nTo direct Square to generate a 16-digit GAN, omit `gan_source` and `gan`.\n\nTo provide a custom GAN, include `gan_source` and `gan`.\n- For `gan_source`, specify `OTHER`. \n- For `gan`, provide a custom GAN containing 8 to 20 alphanumeric characters. The GAN must be \nunique for the seller and cannot start with the same bank identification number (BIN) as major \ncredit cards. Do not use GANs that are easy to guess (such as 12345678) because they greatly \nincrease the risk of fraud. It is the responsibility of the developer to ensure the security \nof their custom GANs. For more information, see \n[Custom GANs](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api#custom-gans). \n\nTo register an unused, physical gift card that the seller previously ordered from Square, \ninclude `gan` and provide the GAN that is printed on the gift card.", "readOnly": false, "required": true } ] }, { "name": "GiftCard", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the gift card.", "readOnly": true, "required": false }, { "name": "type", "type": "#/components/schemas/GiftCardType", "description": "The gift card type.\n", "readOnly": false, "required": true }, { "name": "gan_source", "type": "#/components/schemas/GiftCardGANSource", "description": "The source that generated the gift card account number (GAN). The default value is `SQUARE`.\n", "readOnly": false, "required": false }, { "name": "state", "type": "#/components/schemas/GiftCardStatus", "description": "The current gift card state.\n", "readOnly": true, "required": false }, { "name": "balance_money", "type": "#/components/schemas/Money", "description": "The current gift card balance. This balance is always greater than or equal to zero.", "readOnly": true, "required": false }, { "name": "gan", "type": "string", "description": "The gift card account number (GAN). Buyers can use the GAN to make purchases or check \nthe gift card balance.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the gift card was created, in RFC 3339 format. \nIn the case of a digital gift card, it is the time when you create a card \n(using the Square Point of Sale application, Seller Dashboard, or Gift Cards API). \nIn the case of a plastic gift card, it is the time when Square associates the card with the \nseller at the time of activation.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "customer_ids", "type": "array", "description": "The IDs of the [customer profiles](entity:Customer) to whom this gift card is linked.", "readOnly": true, "required": false } ] }, { "name": "GiftCardType", "properties": [] }, { "name": "GiftCardGANSource", "properties": [] }, { "name": "GiftCardStatus", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] } ], "RetrieveGiftCardFromGANRequest": [ { "name": "RetrieveGiftCardFromGANRequest", "properties": [ { "name": "gan", "type": "string", "description": "The gift card account number (GAN) of the gift card to retrieve.\nThe maximum length of a GAN is 255 digits to account for third-party GANs that have been imported.\nSquare-issued gift cards have 16-digit GANs.", "readOnly": false, "required": true } ] } ], "RetrieveGiftCardFromNonceRequest": [ { "name": "RetrieveGiftCardFromNonceRequest", "properties": [ { "name": "nonce", "type": "string", "description": "The payment token of the gift card to retrieve. Payment tokens are generated by the \nWeb Payments SDK or In-App Payments SDK.", "readOnly": false, "required": true } ] } ], "LinkCustomerToGiftCardRequest": [ { "name": "LinkCustomerToGiftCardRequest", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer to link to the gift card.", "readOnly": false, "required": true }, { "name": "gift_card_id", "type": "string", "description": "The ID of the gift card to be linked.", "readOnly": false, "required": true } ] } ], "UnlinkCustomerFromGiftCardRequest": [ { "name": "UnlinkCustomerFromGiftCardRequest", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer to unlink from the gift card.", "readOnly": false, "required": true }, { "name": "gift_card_id", "type": "string", "description": "The ID of the gift card to be unlinked.", "readOnly": false, "required": true } ] } ], "RetrieveGiftCardRequest": [ { "name": "RetrieveGiftCardRequest", "properties": [ { "name": "id", "type": "string", "description": "The ID of the gift card to retrieve.", "readOnly": false, "required": true } ] } ], "RetrieveInventoryAdjustmentRequest": [ { "name": "RetrieveInventoryAdjustmentRequest", "properties": [ { "name": "adjustment_id", "type": "string", "description": "ID of the [InventoryAdjustment](entity:InventoryAdjustment) to retrieve.", "readOnly": false, "required": true } ] } ], "BatchChangeInventoryRequest": [ { "name": "BatchChangeInventoryRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A client-supplied, universally unique identifier (UUID) for the\nrequest.\n\nSee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the\n[API Development 101](https://developer.squareup.com/docs/buildbasics) section for more\ninformation.", "readOnly": false, "required": true }, { "name": "changes", "type": "array", "description": "The set of physical counts and inventory adjustments to be made.\nChanges are applied based on the client-supplied timestamp and may be sent\nout of order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/InventoryChange" }, { "name": "ignore_unchanged_counts", "type": "boolean", "description": "Indicates whether the current physical count should be ignored if\nthe quantity is unchanged since the last physical count. Default: `true`.", "readOnly": false, "required": false } ] }, { "name": "InventoryChange", "properties": [ { "name": "type", "type": "#/components/schemas/InventoryChangeType", "description": "Indicates how the inventory change is applied. See\n[InventoryChangeType](entity:InventoryChangeType) for all possible values.\n", "readOnly": false, "required": false }, { "name": "physical_count", "type": "#/components/schemas/InventoryPhysicalCount", "description": "Contains details about the physical count when `type` is\n`PHYSICAL_COUNT`, and is unset for all other change types.", "readOnly": false, "required": false }, { "name": "adjustment", "type": "#/components/schemas/InventoryAdjustment", "description": "Contains details about the inventory adjustment when `type` is\n`ADJUSTMENT`, and is unset for all other change types.", "readOnly": false, "required": false }, { "name": "transfer", "type": "#/components/schemas/InventoryTransfer", "description": "Contains details about the inventory transfer when `type` is\n`TRANSFER`, and is unset for all other change types.\n\n_Note:_ An [InventoryTransfer](entity:InventoryTransfer) object can only be set in the input to the\n[BatchChangeInventory](api-endpoint:Inventory-BatchChangeInventory) endpoint when the seller has an active Retail Plus subscription.", "readOnly": false, "required": false }, { "name": "measurement_unit", "type": "#/components/schemas/CatalogMeasurementUnit", "description": "The [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) object representing the catalog measurement unit associated with the inventory change.", "readOnly": true, "required": false }, { "name": "measurement_unit_id", "type": "string", "description": "The ID of the [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) object representing the catalog measurement unit associated with the inventory change.", "readOnly": true, "required": false } ] }, { "name": "InventoryChangeType", "properties": [] }, { "name": "InventoryPhysicalCount", "properties": [ { "name": "id", "type": "string", "description": "A unique Square-generated ID for the\n[InventoryPhysicalCount](entity:InventoryPhysicalCount).", "readOnly": false, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional ID provided by the application to tie the\n[InventoryPhysicalCount](entity:InventoryPhysicalCount) to an external\nsystem.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The Square-generated ID of the\n[CatalogObject](entity:CatalogObject) being tracked.", "readOnly": false, "required": false }, { "name": "catalog_object_type", "type": "string", "description": "The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. \n\nThe Inventory API supports setting and reading the `\"catalog_object_type\": \"ITEM_VARIATION\"` field value. \nIn addition, it can also read the `\"catalog_object_type\": \"ITEM\"` field value that is set by the Square Restaurants app.", "readOnly": false, "required": false }, { "name": "state", "type": "#/components/schemas/InventoryState", "description": "The current [inventory state](entity:InventoryState) for the related\nquantity of items.\n", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The Square-generated ID of the [Location](entity:Location) where the related\nquantity of items is being tracked.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The number of items affected by the physical count as a decimal string.\nThe number can support up to 5 digits after the decimal point.", "readOnly": false, "required": false }, { "name": "source", "type": "#/components/schemas/SourceApplication", "description": "Information about the application with which the\nphysical count is submitted.", "readOnly": true, "required": false }, { "name": "employee_id", "type": "string", "description": "The Square-generated ID of the [Employee](entity:Employee) responsible for the\nphysical count.", "readOnly": false, "required": false }, { "name": "team_member_id", "type": "string", "description": "The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the\nphysical count.", "readOnly": false, "required": false }, { "name": "occurred_at", "type": "string", "description": "A client-generated RFC 3339-formatted timestamp that indicates when\nthe physical count was examined. For physical count updates, the `occurred_at`\ntimestamp cannot be older than 24 hours or in the future relative to the\ntime of the request.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "An RFC 3339-formatted timestamp that indicates when the physical count is received.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "InventoryState", "properties": [] }, { "name": "SourceApplication", "properties": [ { "name": "product", "type": "#/components/schemas/Product", "description": "__Read only__ The [product](entity:Product) type of the application.\n", "readOnly": false, "required": false }, { "name": "application_id", "type": "string", "description": "__Read only__ The Square-assigned ID of the application. This field is used only if the\n[product](entity:Product) type is `EXTERNAL_API`.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "__Read only__ The display name of the application\n(for example, `\"Custom Application\"` or `\"Square POS 4.74 for Android\"`).", "readOnly": false, "required": false } ] }, { "name": "Product", "properties": [] }, { "name": "InventoryAdjustment", "properties": [ { "name": "id", "type": "string", "description": "A unique ID generated by Square for the\n`InventoryAdjustment`.", "readOnly": false, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional ID provided by the application to tie the\n`InventoryAdjustment` to an external\nsystem.", "readOnly": false, "required": false }, { "name": "from_state", "type": "#/components/schemas/InventoryState", "description": "The [inventory state](entity:InventoryState) of the related quantity\nof items before the adjustment.\n", "readOnly": false, "required": false }, { "name": "to_state", "type": "#/components/schemas/InventoryState", "description": "The [inventory state](entity:InventoryState) of the related quantity\nof items after the adjustment.\n", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The Square-generated ID of the [Location](entity:Location) where the related\nquantity of items is being tracked.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The Square-generated ID of the\n[CatalogObject](entity:CatalogObject) being tracked.", "readOnly": false, "required": false }, { "name": "catalog_object_type", "type": "string", "description": "The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. \n\nThe Inventory API supports setting and reading the `\"catalog_object_type\": \"ITEM_VARIATION\"` field value. \nIn addition, it can also read the `\"catalog_object_type\": \"ITEM\"` field value that is set by the Square Restaurants app.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The number of items affected by the adjustment as a decimal string.\nCan support up to 5 digits after the decimal point.", "readOnly": false, "required": false }, { "name": "total_price_money", "type": "#/components/schemas/Money", "description": "The total price paid for goods associated with the\nadjustment. Present if and only if `to_state` is `SOLD`. Always\nnon-negative.", "readOnly": true, "required": false }, { "name": "occurred_at", "type": "string", "description": "A client-generated RFC 3339-formatted timestamp that indicates when\nthe inventory adjustment took place. For inventory adjustment updates, the `occurred_at`\ntimestamp cannot be older than 24 hours or in the future relative to the\ntime of the request.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "An RFC 3339-formatted timestamp that indicates when the inventory adjustment is received.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "source", "type": "#/components/schemas/SourceApplication", "description": "Information about the application that caused the\ninventory adjustment.", "readOnly": true, "required": false }, { "name": "employee_id", "type": "string", "description": "The Square-generated ID of the [Employee](entity:Employee) responsible for the\ninventory adjustment.", "readOnly": false, "required": false }, { "name": "team_member_id", "type": "string", "description": "The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the\ninventory adjustment.", "readOnly": false, "required": false }, { "name": "transaction_id", "type": "string", "description": "The Square-generated ID of the [Transaction](entity:Transaction) that\ncaused the adjustment. Only relevant for payment-related state\ntransitions.", "readOnly": true, "required": false }, { "name": "refund_id", "type": "string", "description": "The Square-generated ID of the [Refund](entity:Refund) that\ncaused the adjustment. Only relevant for refund-related state\ntransitions.", "readOnly": true, "required": false }, { "name": "purchase_order_id", "type": "string", "description": "The Square-generated ID of the purchase order that caused the\nadjustment. Only relevant for state transitions from the Square for Retail\napp.", "readOnly": true, "required": false }, { "name": "goods_receipt_id", "type": "string", "description": "The Square-generated ID of the goods receipt that caused the\nadjustment. Only relevant for state transitions from the Square for Retail\napp.", "readOnly": true, "required": false }, { "name": "adjustment_group", "type": "#/components/schemas/InventoryAdjustmentGroup", "description": "An adjustment group bundling the related adjustments of item variations through stock conversions in a single inventory event.", "readOnly": true, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "InventoryAdjustmentGroup", "properties": [ { "name": "id", "type": "string", "description": "A unique ID generated by Square for the\n`InventoryAdjustmentGroup`.", "readOnly": true, "required": false }, { "name": "root_adjustment_id", "type": "string", "description": "The inventory adjustment of the composed variation.", "readOnly": true, "required": false }, { "name": "from_state", "type": "#/components/schemas/InventoryState", "description": "Representative `from_state` for adjustments within the group. For example, for a group adjustment from `IN_STOCK` to `SOLD`,\nthere can be two component adjustments in the group: one from `IN_STOCK`to `COMPOSED` and the other one from `COMPOSED` to `SOLD`.\nHere, the representative `from_state` for the `InventoryAdjustmentGroup` is `IN_STOCK`.\n", "readOnly": true, "required": false }, { "name": "to_state", "type": "#/components/schemas/InventoryState", "description": "Representative `to_state` for adjustments within group. For example, for a group adjustment from `IN_STOCK` to `SOLD`,\nthe two component adjustments in the group can be from `IN_STOCK` to `COMPOSED` and from `COMPOSED` to `SOLD`.\nHere, the representative `to_state` of the `InventoryAdjustmentGroup` is `SOLD`.\n", "readOnly": true, "required": false } ] }, { "name": "InventoryTransfer", "properties": [ { "name": "id", "type": "string", "description": "A unique ID generated by Square for the\n`InventoryTransfer`.", "readOnly": false, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional ID provided by the application to tie the\n`InventoryTransfer` to an external system.", "readOnly": false, "required": false }, { "name": "state", "type": "#/components/schemas/InventoryState", "description": "The [inventory state](entity:InventoryState) for the quantity of\nitems being transferred.\n", "readOnly": false, "required": false }, { "name": "from_location_id", "type": "string", "description": "The Square-generated ID of the [Location](entity:Location) where the related\nquantity of items was tracked before the transfer.", "readOnly": false, "required": false }, { "name": "to_location_id", "type": "string", "description": "The Square-generated ID of the [Location](entity:Location) where the related\nquantity of items was tracked after the transfer.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The Square-generated ID of the\n[CatalogObject](entity:CatalogObject) being tracked.", "readOnly": false, "required": false }, { "name": "catalog_object_type", "type": "string", "description": "The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. \n\nThe Inventory API supports setting and reading the `\"catalog_object_type\": \"ITEM_VARIATION\"` field value. \nIn addition, it can also read the `\"catalog_object_type\": \"ITEM\"` field value that is set by the Square Restaurants app.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The number of items affected by the transfer as a decimal string.\nCan support up to 5 digits after the decimal point.", "readOnly": false, "required": false }, { "name": "occurred_at", "type": "string", "description": "A client-generated RFC 3339-formatted timestamp that indicates when\nthe transfer took place. For write actions, the `occurred_at` timestamp\ncannot be older than 24 hours or in the future relative to the time of the\nrequest.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "An RFC 3339-formatted timestamp that indicates when Square\nreceived the transfer request.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "source", "type": "#/components/schemas/SourceApplication", "description": "Information about the application that initiated the\ninventory transfer.", "readOnly": true, "required": false }, { "name": "employee_id", "type": "string", "description": "The Square-generated ID of the [Employee](entity:Employee) responsible for the\ninventory transfer.", "readOnly": false, "required": false }, { "name": "team_member_id", "type": "string", "description": "The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the\ninventory transfer.", "readOnly": false, "required": false } ] }, { "name": "CatalogMeasurementUnit", "properties": [ { "name": "measurement_unit", "type": "#/components/schemas/MeasurementUnit", "description": "Indicates the unit used to measure the quantity of a catalog item variation.", "readOnly": false, "required": false }, { "name": "precision", "type": "integer", "description": "An integer between 0 and 5 that represents the maximum number of\npositions allowed after the decimal in quantities measured with this unit.\nFor example:\n\n- if the precision is 0, the quantity can be 1, 2, 3, etc.\n- if the precision is 1, the quantity can be 0.1, 0.2, etc.\n- if the precision is 2, the quantity can be 0.01, 0.12, etc.\n\nDefault: 3", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnit", "properties": [ { "name": "custom_unit", "type": "#/components/schemas/MeasurementUnitCustom", "description": "A custom unit of measurement defined by the seller using the Point of Sale\napp or ad-hoc as an order line item.", "readOnly": false, "required": false }, { "name": "area_unit", "type": "#/components/schemas/MeasurementUnitArea", "description": "Represents a standard area unit.\n", "readOnly": false, "required": false }, { "name": "length_unit", "type": "#/components/schemas/MeasurementUnitLength", "description": "Represents a standard length unit.\n", "readOnly": false, "required": false }, { "name": "volume_unit", "type": "#/components/schemas/MeasurementUnitVolume", "description": "Represents a standard volume unit.\n", "readOnly": false, "required": false }, { "name": "weight_unit", "type": "#/components/schemas/MeasurementUnitWeight", "description": "Represents a standard unit of weight or mass.\n", "readOnly": false, "required": false }, { "name": "generic_unit", "type": "#/components/schemas/MeasurementUnitGeneric", "description": "Reserved for API integrations that lack the ability to specify a real measurement unit\n", "readOnly": false, "required": false }, { "name": "time_unit", "type": "#/components/schemas/MeasurementUnitTime", "description": "Represents a standard unit of time.\n", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/MeasurementUnitUnitType", "description": "Represents the type of the measurement unit.\n", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnitCustom", "properties": [ { "name": "name", "type": "string", "description": "The name of the custom unit, for example \"bushel\".", "readOnly": false, "required": true }, { "name": "abbreviation", "type": "string", "description": "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears\nin the cart for the Point of Sale app, and in reports.", "readOnly": false, "required": true } ] }, { "name": "MeasurementUnitArea", "properties": [] }, { "name": "MeasurementUnitLength", "properties": [] }, { "name": "MeasurementUnitVolume", "properties": [] }, { "name": "MeasurementUnitWeight", "properties": [] }, { "name": "MeasurementUnitGeneric", "properties": [] }, { "name": "MeasurementUnitTime", "properties": [] }, { "name": "MeasurementUnitUnitType", "properties": [] } ], "BatchRetrieveInventoryChangesRequest": [ { "name": "BatchRetrieveInventoryChangesRequest", "properties": [ { "name": "catalog_object_ids", "type": "array", "description": "The filter to return results by `CatalogObject` ID.\nThe filter is only applicable when set. The default value is null.", "readOnly": false, "required": false }, { "name": "location_ids", "type": "array", "description": "The filter to return results by `Location` ID.\nThe filter is only applicable when set. The default value is null.", "readOnly": false, "required": false }, { "name": "types", "type": "array", "description": "The filter to return results by `InventoryChangeType` values other than `TRANSFER`.\nThe default value is `[PHYSICAL_COUNT, ADJUSTMENT]`.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/InventoryChangeType" }, { "name": "states", "type": "array", "description": "The filter to return `ADJUSTMENT` query results by\n`InventoryState`. This filter is only applied when set.\nThe default value is null.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/InventoryState" }, { "name": "updated_after", "type": "string", "description": "The filter to return results with their `calculated_at` value\nafter the given time as specified in an RFC 3339 timestamp.\nThe default value is the UNIX epoch of (`1970-01-01T00:00:00Z`).\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "updated_before", "type": "string", "description": "The filter to return results with their `created_at` or `calculated_at` value\nstrictly before the given time as specified in an RFC 3339 timestamp.\nThe default value is the UNIX epoch of (`1970-01-01T00:00:00Z`).\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for the original query.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The number of [records](entity:InventoryChange) to return.", "readOnly": false, "required": false } ] }, { "name": "InventoryChangeType", "properties": [] }, { "name": "InventoryState", "properties": [] } ], "BatchRetrieveInventoryCountsRequest": [ { "name": "BatchRetrieveInventoryCountsRequest", "properties": [ { "name": "catalog_object_ids", "type": "array", "description": "The filter to return results by `CatalogObject` ID.\nThe filter is applicable only when set. The default is null.", "readOnly": false, "required": false }, { "name": "location_ids", "type": "array", "description": "The filter to return results by `Location` ID.\nThis filter is applicable only when set. The default is null.", "readOnly": false, "required": false }, { "name": "updated_after", "type": "string", "description": "The filter to return results with their `calculated_at` value\nafter the given time as specified in an RFC 3339 timestamp.\nThe default value is the UNIX epoch of (`1970-01-01T00:00:00Z`).\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for the original query.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.", "readOnly": false, "required": false }, { "name": "states", "type": "array", "description": "The filter to return results by `InventoryState`. The filter is only applicable when set.\nIgnored are untracked states of `NONE`, `SOLD`, and `UNLINKED_RETURN`.\nThe default is null.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/InventoryState" }, { "name": "limit", "type": "integer", "description": "The number of [records](entity:InventoryCount) to return.", "readOnly": false, "required": false } ] }, { "name": "InventoryState", "properties": [] } ], "RetrieveInventoryPhysicalCountRequest": [ { "name": "RetrieveInventoryPhysicalCountRequest", "properties": [ { "name": "physical_count_id", "type": "string", "description": "ID of the\n[InventoryPhysicalCount](entity:InventoryPhysicalCount) to retrieve.", "readOnly": false, "required": true } ] } ], "RetrieveInventoryTransferRequest": [ { "name": "RetrieveInventoryTransferRequest", "properties": [ { "name": "transfer_id", "type": "string", "description": "ID of the [InventoryTransfer](entity:InventoryTransfer) to retrieve.", "readOnly": false, "required": true } ] } ], "RetrieveInventoryCountRequest": [ { "name": "RetrieveInventoryCountRequest", "properties": [ { "name": "location_ids", "type": "string", "description": "The [Location](entity:Location) IDs to look up as a comma-separated\nlist. An empty list queries all locations.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for the original query.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "ID of the [CatalogObject](entity:CatalogObject) to retrieve.", "readOnly": false, "required": true } ] } ], "ListInvoicesRequest": [ { "name": "ListInvoicesRequest", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the location for which to list invoices.", "readOnly": false, "required": true }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint. \nProvide this cursor to retrieve the next set of results for your original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of invoices to return (200 is the maximum `limit`). \nIf not provided, the server uses a default limit of 100 invoices.", "readOnly": false, "required": false } ] } ], "CreateInvoiceRequest": [ { "name": "CreateInvoiceRequest", "properties": [ { "name": "invoice", "type": "#/components/schemas/Invoice", "description": "The invoice to create.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies the `CreateInvoice` request. If you do not \nprovide `idempotency_key` (or provide an empty string as the value), the endpoint \ntreats each request as independent.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false } ] }, { "name": "Invoice", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the invoice.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "The Square-assigned version number, which is incremented each time an update is committed to the invoice.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the location that this invoice is associated with. \n\nIf specified in a `CreateInvoice` request, the value must match the `location_id` of the associated order.", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the [order](entity:Order) for which the invoice is created. \nThis field is required when creating an invoice, and the order must be in the `OPEN` state.\n\nTo view the line items and other information for the associated order, call the \n[RetrieveOrder](api-endpoint:Orders-RetrieveOrder) endpoint using the order ID.", "readOnly": false, "required": false }, { "name": "primary_recipient", "type": "#/components/schemas/InvoiceRecipient", "description": "The customer who receives the invoice. This customer data is displayed on the invoice and used by Square to deliver the invoice. \n\nThis field is required to publish an invoice, and it must specify the `customer_id`.", "readOnly": false, "required": false }, { "name": "payment_requests", "type": "array", "description": "The payment schedule for the invoice, represented by one or more payment requests that\ndefine payment settings, such as amount due and due date. An invoice supports the following payment request combinations:\n- One balance\n- One deposit with one balance\n- 2–12 installments \n- One deposit with 2–12 installments\n\nThis field is required when creating an invoice. It must contain at least one payment request. \nAll payment requests for the invoice must equal the total order amount. For more information, see \n[Configuring payment requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).\n\nAdding `INSTALLMENT` payment requests to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/InvoicePaymentRequest" }, { "name": "delivery_method", "type": "#/components/schemas/InvoiceDeliveryMethod", "description": "The delivery method that Square uses to send the invoice, reminders, and receipts to\nthe customer. After the invoice is published, Square processes the invoice based on the delivery\nmethod and payment request settings, either immediately or on the `scheduled_at` date, if specified.\nFor example, Square might send the invoice or receipt for an automatic payment. For invoices with\nautomatic payments, this field must be set to `EMAIL`.\n\nOne of the following is required when creating an invoice:\n- (Recommended) This `delivery_method` field. To configure an automatic payment, the\n`automatic_payment_source` field of the payment request is also required.\n- The deprecated `request_method` field of the payment request. Note that `invoice`\nobjects returned in responses do not include `request_method`.\n", "readOnly": false, "required": false }, { "name": "invoice_number", "type": "string", "description": "A user-friendly invoice number that is displayed on the invoice. The value is unique within a location.\nIf not provided when creating an invoice, Square assigns a value.\nIt increments from 1 and is padded with zeros making it 7 characters long\n(for example, 0000001 and 0000002).", "readOnly": false, "required": false }, { "name": "title", "type": "string", "description": "The title of the invoice, which is displayed on the invoice.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The description of the invoice, which is displayed on the invoice.", "readOnly": false, "required": false }, { "name": "scheduled_at", "type": "string", "description": "The timestamp when the invoice is scheduled for processing, in RFC 3339 format.\nAfter the invoice is published, Square processes the invoice on the specified date,\naccording to the delivery method and payment request settings.\n\nIf the field is not set, Square processes the invoice immediately after it is published.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "public_url", "type": "string", "description": "The URL of the Square-hosted invoice page.\nAfter you publish the invoice using the `PublishInvoice` endpoint, Square hosts the invoice\npage and returns the page URL in the response.", "readOnly": true, "required": false }, { "name": "next_payment_amount_money", "type": "#/components/schemas/Money", "description": "The current amount due for the invoice. In addition to the\namount due on the next payment request, this includes any overdue payment amounts.", "readOnly": true, "required": false }, { "name": "status", "type": "#/components/schemas/InvoiceStatus", "description": "The status of the invoice.\n", "readOnly": true, "required": false }, { "name": "timezone", "type": "string", "description": "The time zone used to interpret calendar dates on the invoice, such as `due_date`.\nWhen an invoice is created, this field is set to the `timezone` specified for the seller\nlocation. The value cannot be changed.\n\nFor example, a payment `due_date` of 2021-03-09 with a `timezone` of America/Los\\_Angeles\nbecomes overdue at midnight on March 9 in America/Los\\_Angeles (which equals a UTC timestamp\nof 2021-03-10T08:00:00Z).", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the invoice was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the invoice was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "accepted_payment_methods", "type": "#/components/schemas/InvoiceAcceptedPaymentMethods", "description": "The payment methods that customers can use to pay the invoice on the Square-hosted\ninvoice page. This setting is independent of any automatic payment requests for the invoice.\n\nThis field is required when creating an invoice and must set at least one payment method to `true`.", "readOnly": false, "required": false }, { "name": "custom_fields", "type": "array", "description": "Additional seller-defined fields that are displayed on the invoice. For more information, see\n[Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).\n\nAdding custom fields to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).\n\nMax: 2 custom fields", "readOnly": false, "required": false, "arrayType": "#/components/schemas/InvoiceCustomField" }, { "name": "subscription_id", "type": "string", "description": "The ID of the [subscription](entity:Subscription) associated with the invoice.\nThis field is present only on subscription billing invoices.", "readOnly": true, "required": false }, { "name": "sale_or_service_date", "type": "string", "description": "The date of the sale or the date that the service is rendered, in `YYYY-MM-DD` format.\nThis field can be used to specify a past or future date which is displayed on the invoice.", "readOnly": false, "required": false }, { "name": "payment_conditions", "type": "string", "description": "**France only.** The payment terms and conditions that are displayed on the invoice. For more information, \nsee [Payment conditions](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions).\n\nFor countries other than France, Square returns an `INVALID_REQUEST_ERROR` with a `BAD_REQUEST` code and \n\"Payment conditions are not supported for this location's country\" detail if this field is included in `CreateInvoice` or `UpdateInvoice` requests.", "readOnly": false, "required": false }, { "name": "store_payment_method_enabled", "type": "boolean", "description": "Indicates whether to allow a customer to save a credit or debit card as a card on file or a bank transfer as a\nbank account on file. If `true`, Square displays a __Save my card on file__ or __Save my bank on file__ checkbox on the\ninvoice payment page. Stored payment information can be used for future automatic payments. The default value is `false`.", "readOnly": false, "required": false }, { "name": "attachments", "type": "array", "description": "Metadata about the attachments on the invoice. Invoice attachments are managed using the\n[CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment) and [DeleteInvoiceAttachment](api-endpoint:Invoices-DeleteInvoiceAttachment) endpoints.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/InvoiceAttachment" } ] }, { "name": "InvoiceRecipient", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer. This is the customer profile ID that \nyou provide when creating a draft invoice.", "readOnly": false, "required": false }, { "name": "given_name", "type": "string", "description": "The recipient's given (that is, first) name.", "readOnly": true, "required": false }, { "name": "family_name", "type": "string", "description": "The recipient's family (that is, last) name.", "readOnly": true, "required": false }, { "name": "email_address", "type": "string", "description": "The recipient's email address.", "readOnly": true, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The recipient's physical address.", "readOnly": true, "required": false }, { "name": "phone_number", "type": "string", "description": "The recipient's phone number.", "readOnly": true, "required": false }, { "name": "company_name", "type": "string", "description": "The name of the recipient's company.", "readOnly": true, "required": false }, { "name": "tax_ids", "type": "#/components/schemas/InvoiceRecipientTaxIds", "description": "The recipient's tax IDs. The country of the seller account determines whether this field \nis available for the customer. For more information, see [Invoice recipient tax IDs](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids).", "readOnly": true, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "InvoiceRecipientTaxIds", "properties": [ { "name": "eu_vat", "type": "string", "description": "The EU VAT identification number for the invoice recipient. For example, `IE3426675K`.", "readOnly": true, "required": false } ] }, { "name": "InvoicePaymentRequest", "properties": [ { "name": "uid", "type": "string", "description": "The Square-generated ID of the payment request in an [invoice](entity:Invoice).", "readOnly": false, "required": false }, { "name": "request_method", "type": "#/components/schemas/InvoiceRequestMethod", "description": "Indicates how Square processes the payment request. DEPRECATED at version 2021-01-21. Replaced by the\n`Invoice.delivery_method` and `InvoicePaymentRequest.automatic_payment_source` fields.\n\nOne of the following is required when creating an invoice:\n- (Recommended) The `delivery_method` field of the invoice. To configure an automatic payment, the\n`automatic_payment_source` field of the payment request is also required.\n- This `request_method` field. Note that `invoice` objects returned in responses do not include `request_method`.\n", "readOnly": false, "required": false }, { "name": "request_type", "type": "#/components/schemas/InvoiceRequestType", "description": "Identifies the payment request type. This type defines how the payment request amount is determined. \nThis field is required to create a payment request.\n", "readOnly": false, "required": false }, { "name": "due_date", "type": "string", "description": "The due date (in the invoice's time zone) for the payment request, in `YYYY-MM-DD` format. This field\nis required to create a payment request. If an `automatic_payment_source` is defined for the request, Square\ncharges the payment source on this date.\n\nAfter this date, the invoice becomes overdue. For example, a payment `due_date` of 2021-03-09 with a `timezone`\nof America/Los\\_Angeles becomes overdue at midnight on March 9 in America/Los\\_Angeles (which equals a UTC\ntimestamp of 2021-03-10T08:00:00Z).", "readOnly": false, "required": false }, { "name": "fixed_amount_requested_money", "type": "#/components/schemas/Money", "description": "If the payment request specifies `DEPOSIT` or `INSTALLMENT` as the `request_type`, \nthis indicates the request amount.\nYou cannot specify this when `request_type` is `BALANCE` or when the \npayment request includes the `percentage_requested` field.", "readOnly": false, "required": false }, { "name": "percentage_requested", "type": "string", "description": "Specifies the amount for the payment request in percentage:\n\n- When the payment `request_type` is `DEPOSIT`, it is the percentage of the order's total amount.\n- When the payment `request_type` is `INSTALLMENT`, it is the percentage of the order's total less \nthe deposit, if requested. The sum of the `percentage_requested` in all installment \npayment requests must be equal to 100.\n\nYou cannot specify this when the payment `request_type` is `BALANCE` or when the \npayment request specifies the `fixed_amount_requested_money` field.", "readOnly": false, "required": false }, { "name": "tipping_enabled", "type": "boolean", "description": "If set to true, the Square-hosted invoice page (the `public_url` field of the invoice) \nprovides a place for the customer to pay a tip. \n\nThis field is allowed only on the final payment request \nand the payment `request_type` must be `BALANCE` or `INSTALLMENT`.", "readOnly": false, "required": false }, { "name": "automatic_payment_source", "type": "#/components/schemas/InvoiceAutomaticPaymentSource", "description": "The payment method for an automatic payment.\n\nThe default value is `NONE`.\n", "readOnly": false, "required": false }, { "name": "card_id", "type": "string", "description": "The ID of the credit or debit card on file to charge for the payment request. To get the cards on file for a customer,\ncall [ListCards](api-endpoint:Cards-ListCards) and include the `customer_id` of the invoice recipient.", "readOnly": false, "required": false }, { "name": "reminders", "type": "array", "description": "A list of one or more reminders to send for the payment request.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/InvoicePaymentReminder" }, { "name": "computed_amount_money", "type": "#/components/schemas/Money", "description": "The amount of the payment request, computed using the order amount and information from the various payment\nrequest fields (`request_type`, `fixed_amount_requested_money`, and `percentage_requested`).", "readOnly": true, "required": false }, { "name": "total_completed_amount_money", "type": "#/components/schemas/Money", "description": "The amount of money already paid for the specific payment request. \nThis amount might include a rounding adjustment if the most recent invoice payment \nwas in cash in a currency that rounds cash payments (such as, `CAD` or `AUD`).", "readOnly": true, "required": false }, { "name": "rounding_adjustment_included_money", "type": "#/components/schemas/Money", "description": "If the most recent payment was a cash payment \nin a currency that rounds cash payments (such as, `CAD` or `AUD`) and the payment \nis rounded from `computed_amount_money` in the payment request, then this \nfield specifies the rounding adjustment applied. This amount \nmight be negative.", "readOnly": true, "required": false } ] }, { "name": "InvoiceRequestMethod", "properties": [] }, { "name": "InvoiceRequestType", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "InvoiceAutomaticPaymentSource", "properties": [] }, { "name": "InvoicePaymentReminder", "properties": [ { "name": "uid", "type": "string", "description": "A Square-assigned ID that uniquely identifies the reminder within the\n`InvoicePaymentRequest`.", "readOnly": true, "required": false }, { "name": "relative_scheduled_days", "type": "integer", "description": "The number of days before (a negative number) or after (a positive number)\nthe payment request `due_date` when the reminder is sent. For example, -3 indicates that\nthe reminder should be sent 3 days before the payment request `due_date`.", "readOnly": false, "required": false }, { "name": "message", "type": "string", "description": "The reminder message.", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/InvoicePaymentReminderStatus", "description": "The status of the reminder.\n", "readOnly": true, "required": false }, { "name": "sent_at", "type": "string", "description": "If sent, the timestamp when the reminder was sent, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "InvoicePaymentReminderStatus", "properties": [] }, { "name": "InvoiceDeliveryMethod", "properties": [] }, { "name": "InvoiceStatus", "properties": [] }, { "name": "InvoiceAcceptedPaymentMethods", "properties": [ { "name": "card", "type": "boolean", "description": "Indicates whether credit card or debit card payments are accepted. The default value is `false`.", "readOnly": false, "required": false }, { "name": "square_gift_card", "type": "boolean", "description": "Indicates whether Square gift card payments are accepted. The default value is `false`.", "readOnly": false, "required": false }, { "name": "bank_account", "type": "boolean", "description": "Indicates whether ACH bank transfer payments are accepted. The default value is `false`.", "readOnly": false, "required": false }, { "name": "buy_now_pay_later", "type": "boolean", "description": "Indicates whether Afterpay (also known as Clearpay) payments are accepted. The default value is `false`.\n\nThis option is allowed only for invoices that have a single payment request of the `BALANCE` type. This payment method is\nsupported if the seller account accepts Afterpay payments and the seller location is in a country where Afterpay\ninvoice payments are supported. As a best practice, consider enabling an additional payment method when allowing\n`buy_now_pay_later` payments. For more information, including detailed requirements and processing limits, see\n[Buy Now Pay Later payments with Afterpay](https://developer.squareup.com/docs/invoices-api/overview#buy-now-pay-later).", "readOnly": false, "required": false }, { "name": "cash_app_pay", "type": "boolean", "description": "Indicates whether Cash App payments are accepted. The default value is `false`.\n\nThis payment method is supported only for seller [locations](entity:Location) in the United States.", "readOnly": false, "required": false } ] }, { "name": "InvoiceCustomField", "properties": [ { "name": "label", "type": "string", "description": "The label or title of the custom field. This field is required for a custom field.", "readOnly": false, "required": false }, { "name": "value", "type": "string", "description": "The text of the custom field. If omitted, only the label is rendered.", "readOnly": false, "required": false }, { "name": "placement", "type": "#/components/schemas/InvoiceCustomFieldPlacement", "description": "The location of the custom field on the invoice. This field is required for a custom field.\n", "readOnly": false, "required": false } ] }, { "name": "InvoiceCustomFieldPlacement", "properties": [] }, { "name": "InvoiceAttachment", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the attachment.", "readOnly": true, "required": false }, { "name": "filename", "type": "string", "description": "The file name of the attachment, which is displayed on the invoice.", "readOnly": true, "required": false }, { "name": "description", "type": "string", "description": "The description of the attachment, which is displayed on the invoice.\nThis field maps to the seller-defined **Message** field.", "readOnly": true, "required": false }, { "name": "filesize", "type": "integer", "description": "The file size of the attachment in bytes.", "readOnly": true, "required": false }, { "name": "hash", "type": "string", "description": "The MD5 hash that was generated from the file contents.", "readOnly": true, "required": false }, { "name": "mime_type", "type": "string", "description": "The mime type of the attachment.\nThe following mime types are supported: \nimage/gif, image/jpeg, image/png, image/tiff, image/bmp, application/pdf.", "readOnly": true, "required": false }, { "name": "uploaded_at", "type": "string", "description": "The timestamp when the attachment was uploaded, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "SearchInvoicesRequest": [ { "name": "SearchInvoicesRequest", "properties": [ { "name": "query", "type": "#/components/schemas/InvoiceQuery", "description": "Describes the query criteria for searching invoices.", "readOnly": false, "required": true }, { "name": "limit", "type": "integer", "description": "The maximum number of invoices to return (200 is the maximum `limit`). \nIf not provided, the server uses a default limit of 100 invoices.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint. \nProvide this cursor to retrieve the next set of results for your original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] }, { "name": "InvoiceQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/InvoiceFilter", "description": "Query filters to apply in searching invoices. \nFor more information, see [Search for invoices](https://developer.squareup.com/docs/invoices-api/retrieve-list-search-invoices#search-invoices).", "readOnly": false, "required": true }, { "name": "sort", "type": "#/components/schemas/InvoiceSort", "description": "Describes the sort order for the search result.", "readOnly": false, "required": false } ] }, { "name": "InvoiceFilter", "properties": [ { "name": "location_ids", "type": "array", "description": "Limits the search to the specified locations. A location is required. \nIn the current implementation, only one location can be specified.", "readOnly": false, "required": true }, { "name": "customer_ids", "type": "array", "description": "Limits the search to the specified customers, within the specified locations. \nSpecifying a customer is optional. In the current implementation, \na maximum of one customer can be specified.", "readOnly": false, "required": false } ] }, { "name": "InvoiceSort", "properties": [ { "name": "field", "type": "#/components/schemas/InvoiceSortField", "description": "The field to use for sorting.\n", "readOnly": false, "required": true }, { "name": "order", "type": "#/components/schemas/SortOrder", "description": "The order to use for sorting the results.\n", "readOnly": false, "required": false } ] }, { "name": "InvoiceSortField", "properties": [] }, { "name": "SortOrder", "properties": [] } ], "DeleteInvoiceRequest": [ { "name": "DeleteInvoiceRequest", "properties": [ { "name": "version", "type": "integer", "description": "The version of the [invoice](entity:Invoice) to delete.\nIf you do not know the version, you can call [GetInvoice](api-endpoint:Invoices-GetInvoice) or \n[ListInvoices](api-endpoint:Invoices-ListInvoices).", "readOnly": false, "required": false }, { "name": "invoice_id", "type": "string", "description": "The ID of the invoice to delete.", "readOnly": false, "required": true } ] } ], "GetInvoiceRequest": [ { "name": "GetInvoiceRequest", "properties": [ { "name": "invoice_id", "type": "string", "description": "The ID of the invoice to retrieve.", "readOnly": false, "required": true } ] } ], "UpdateInvoiceRequest": [ { "name": "UpdateInvoiceRequest", "properties": [ { "name": "invoice", "type": "#/components/schemas/Invoice", "description": "The invoice fields to add, change, or clear. Fields can be cleared using\nnull values or the `remove` field (for individual payment requests or reminders).\nThe current invoice `version` is also required. For more information, including requirements,\nlimitations, and more examples, see [Update an Invoice](https://developer.squareup.com/docs/invoices-api/update-invoices).", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies the `UpdateInvoice` request. If you do not\nprovide `idempotency_key` (or provide an empty string as the value), the endpoint\ntreats each request as independent.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "fields_to_clear", "type": "array", "description": "The list of fields to clear. Although this field is currently supported, we\nrecommend using null values or the `remove` field when possible. For examples, see\n[Update an Invoice](https://developer.squareup.com/docs/invoices-api/update-invoices).", "readOnly": false, "required": false }, { "name": "invoice_id", "type": "string", "description": "The ID of the invoice to update.", "readOnly": false, "required": true } ] }, { "name": "Invoice", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the invoice.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "The Square-assigned version number, which is incremented each time an update is committed to the invoice.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the location that this invoice is associated with. \n\nIf specified in a `CreateInvoice` request, the value must match the `location_id` of the associated order.", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the [order](entity:Order) for which the invoice is created. \nThis field is required when creating an invoice, and the order must be in the `OPEN` state.\n\nTo view the line items and other information for the associated order, call the \n[RetrieveOrder](api-endpoint:Orders-RetrieveOrder) endpoint using the order ID.", "readOnly": false, "required": false }, { "name": "primary_recipient", "type": "#/components/schemas/InvoiceRecipient", "description": "The customer who receives the invoice. This customer data is displayed on the invoice and used by Square to deliver the invoice. \n\nThis field is required to publish an invoice, and it must specify the `customer_id`.", "readOnly": false, "required": false }, { "name": "payment_requests", "type": "array", "description": "The payment schedule for the invoice, represented by one or more payment requests that\ndefine payment settings, such as amount due and due date. An invoice supports the following payment request combinations:\n- One balance\n- One deposit with one balance\n- 2–12 installments \n- One deposit with 2–12 installments\n\nThis field is required when creating an invoice. It must contain at least one payment request. \nAll payment requests for the invoice must equal the total order amount. For more information, see \n[Configuring payment requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).\n\nAdding `INSTALLMENT` payment requests to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/InvoicePaymentRequest" }, { "name": "delivery_method", "type": "#/components/schemas/InvoiceDeliveryMethod", "description": "The delivery method that Square uses to send the invoice, reminders, and receipts to\nthe customer. After the invoice is published, Square processes the invoice based on the delivery\nmethod and payment request settings, either immediately or on the `scheduled_at` date, if specified.\nFor example, Square might send the invoice or receipt for an automatic payment. For invoices with\nautomatic payments, this field must be set to `EMAIL`.\n\nOne of the following is required when creating an invoice:\n- (Recommended) This `delivery_method` field. To configure an automatic payment, the\n`automatic_payment_source` field of the payment request is also required.\n- The deprecated `request_method` field of the payment request. Note that `invoice`\nobjects returned in responses do not include `request_method`.\n", "readOnly": false, "required": false }, { "name": "invoice_number", "type": "string", "description": "A user-friendly invoice number that is displayed on the invoice. The value is unique within a location.\nIf not provided when creating an invoice, Square assigns a value.\nIt increments from 1 and is padded with zeros making it 7 characters long\n(for example, 0000001 and 0000002).", "readOnly": false, "required": false }, { "name": "title", "type": "string", "description": "The title of the invoice, which is displayed on the invoice.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The description of the invoice, which is displayed on the invoice.", "readOnly": false, "required": false }, { "name": "scheduled_at", "type": "string", "description": "The timestamp when the invoice is scheduled for processing, in RFC 3339 format.\nAfter the invoice is published, Square processes the invoice on the specified date,\naccording to the delivery method and payment request settings.\n\nIf the field is not set, Square processes the invoice immediately after it is published.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "public_url", "type": "string", "description": "The URL of the Square-hosted invoice page.\nAfter you publish the invoice using the `PublishInvoice` endpoint, Square hosts the invoice\npage and returns the page URL in the response.", "readOnly": true, "required": false }, { "name": "next_payment_amount_money", "type": "#/components/schemas/Money", "description": "The current amount due for the invoice. In addition to the\namount due on the next payment request, this includes any overdue payment amounts.", "readOnly": true, "required": false }, { "name": "status", "type": "#/components/schemas/InvoiceStatus", "description": "The status of the invoice.\n", "readOnly": true, "required": false }, { "name": "timezone", "type": "string", "description": "The time zone used to interpret calendar dates on the invoice, such as `due_date`.\nWhen an invoice is created, this field is set to the `timezone` specified for the seller\nlocation. The value cannot be changed.\n\nFor example, a payment `due_date` of 2021-03-09 with a `timezone` of America/Los\\_Angeles\nbecomes overdue at midnight on March 9 in America/Los\\_Angeles (which equals a UTC timestamp\nof 2021-03-10T08:00:00Z).", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the invoice was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the invoice was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "accepted_payment_methods", "type": "#/components/schemas/InvoiceAcceptedPaymentMethods", "description": "The payment methods that customers can use to pay the invoice on the Square-hosted\ninvoice page. This setting is independent of any automatic payment requests for the invoice.\n\nThis field is required when creating an invoice and must set at least one payment method to `true`.", "readOnly": false, "required": false }, { "name": "custom_fields", "type": "array", "description": "Additional seller-defined fields that are displayed on the invoice. For more information, see\n[Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).\n\nAdding custom fields to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).\n\nMax: 2 custom fields", "readOnly": false, "required": false, "arrayType": "#/components/schemas/InvoiceCustomField" }, { "name": "subscription_id", "type": "string", "description": "The ID of the [subscription](entity:Subscription) associated with the invoice.\nThis field is present only on subscription billing invoices.", "readOnly": true, "required": false }, { "name": "sale_or_service_date", "type": "string", "description": "The date of the sale or the date that the service is rendered, in `YYYY-MM-DD` format.\nThis field can be used to specify a past or future date which is displayed on the invoice.", "readOnly": false, "required": false }, { "name": "payment_conditions", "type": "string", "description": "**France only.** The payment terms and conditions that are displayed on the invoice. For more information, \nsee [Payment conditions](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions).\n\nFor countries other than France, Square returns an `INVALID_REQUEST_ERROR` with a `BAD_REQUEST` code and \n\"Payment conditions are not supported for this location's country\" detail if this field is included in `CreateInvoice` or `UpdateInvoice` requests.", "readOnly": false, "required": false }, { "name": "store_payment_method_enabled", "type": "boolean", "description": "Indicates whether to allow a customer to save a credit or debit card as a card on file or a bank transfer as a\nbank account on file. If `true`, Square displays a __Save my card on file__ or __Save my bank on file__ checkbox on the\ninvoice payment page. Stored payment information can be used for future automatic payments. The default value is `false`.", "readOnly": false, "required": false }, { "name": "attachments", "type": "array", "description": "Metadata about the attachments on the invoice. Invoice attachments are managed using the\n[CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment) and [DeleteInvoiceAttachment](api-endpoint:Invoices-DeleteInvoiceAttachment) endpoints.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/InvoiceAttachment" } ] }, { "name": "InvoiceRecipient", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer. This is the customer profile ID that \nyou provide when creating a draft invoice.", "readOnly": false, "required": false }, { "name": "given_name", "type": "string", "description": "The recipient's given (that is, first) name.", "readOnly": true, "required": false }, { "name": "family_name", "type": "string", "description": "The recipient's family (that is, last) name.", "readOnly": true, "required": false }, { "name": "email_address", "type": "string", "description": "The recipient's email address.", "readOnly": true, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The recipient's physical address.", "readOnly": true, "required": false }, { "name": "phone_number", "type": "string", "description": "The recipient's phone number.", "readOnly": true, "required": false }, { "name": "company_name", "type": "string", "description": "The name of the recipient's company.", "readOnly": true, "required": false }, { "name": "tax_ids", "type": "#/components/schemas/InvoiceRecipientTaxIds", "description": "The recipient's tax IDs. The country of the seller account determines whether this field \nis available for the customer. For more information, see [Invoice recipient tax IDs](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids).", "readOnly": true, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "InvoiceRecipientTaxIds", "properties": [ { "name": "eu_vat", "type": "string", "description": "The EU VAT identification number for the invoice recipient. For example, `IE3426675K`.", "readOnly": true, "required": false } ] }, { "name": "InvoicePaymentRequest", "properties": [ { "name": "uid", "type": "string", "description": "The Square-generated ID of the payment request in an [invoice](entity:Invoice).", "readOnly": false, "required": false }, { "name": "request_method", "type": "#/components/schemas/InvoiceRequestMethod", "description": "Indicates how Square processes the payment request. DEPRECATED at version 2021-01-21. Replaced by the\n`Invoice.delivery_method` and `InvoicePaymentRequest.automatic_payment_source` fields.\n\nOne of the following is required when creating an invoice:\n- (Recommended) The `delivery_method` field of the invoice. To configure an automatic payment, the\n`automatic_payment_source` field of the payment request is also required.\n- This `request_method` field. Note that `invoice` objects returned in responses do not include `request_method`.\n", "readOnly": false, "required": false }, { "name": "request_type", "type": "#/components/schemas/InvoiceRequestType", "description": "Identifies the payment request type. This type defines how the payment request amount is determined. \nThis field is required to create a payment request.\n", "readOnly": false, "required": false }, { "name": "due_date", "type": "string", "description": "The due date (in the invoice's time zone) for the payment request, in `YYYY-MM-DD` format. This field\nis required to create a payment request. If an `automatic_payment_source` is defined for the request, Square\ncharges the payment source on this date.\n\nAfter this date, the invoice becomes overdue. For example, a payment `due_date` of 2021-03-09 with a `timezone`\nof America/Los\\_Angeles becomes overdue at midnight on March 9 in America/Los\\_Angeles (which equals a UTC\ntimestamp of 2021-03-10T08:00:00Z).", "readOnly": false, "required": false }, { "name": "fixed_amount_requested_money", "type": "#/components/schemas/Money", "description": "If the payment request specifies `DEPOSIT` or `INSTALLMENT` as the `request_type`, \nthis indicates the request amount.\nYou cannot specify this when `request_type` is `BALANCE` or when the \npayment request includes the `percentage_requested` field.", "readOnly": false, "required": false }, { "name": "percentage_requested", "type": "string", "description": "Specifies the amount for the payment request in percentage:\n\n- When the payment `request_type` is `DEPOSIT`, it is the percentage of the order's total amount.\n- When the payment `request_type` is `INSTALLMENT`, it is the percentage of the order's total less \nthe deposit, if requested. The sum of the `percentage_requested` in all installment \npayment requests must be equal to 100.\n\nYou cannot specify this when the payment `request_type` is `BALANCE` or when the \npayment request specifies the `fixed_amount_requested_money` field.", "readOnly": false, "required": false }, { "name": "tipping_enabled", "type": "boolean", "description": "If set to true, the Square-hosted invoice page (the `public_url` field of the invoice) \nprovides a place for the customer to pay a tip. \n\nThis field is allowed only on the final payment request \nand the payment `request_type` must be `BALANCE` or `INSTALLMENT`.", "readOnly": false, "required": false }, { "name": "automatic_payment_source", "type": "#/components/schemas/InvoiceAutomaticPaymentSource", "description": "The payment method for an automatic payment.\n\nThe default value is `NONE`.\n", "readOnly": false, "required": false }, { "name": "card_id", "type": "string", "description": "The ID of the credit or debit card on file to charge for the payment request. To get the cards on file for a customer,\ncall [ListCards](api-endpoint:Cards-ListCards) and include the `customer_id` of the invoice recipient.", "readOnly": false, "required": false }, { "name": "reminders", "type": "array", "description": "A list of one or more reminders to send for the payment request.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/InvoicePaymentReminder" }, { "name": "computed_amount_money", "type": "#/components/schemas/Money", "description": "The amount of the payment request, computed using the order amount and information from the various payment\nrequest fields (`request_type`, `fixed_amount_requested_money`, and `percentage_requested`).", "readOnly": true, "required": false }, { "name": "total_completed_amount_money", "type": "#/components/schemas/Money", "description": "The amount of money already paid for the specific payment request. \nThis amount might include a rounding adjustment if the most recent invoice payment \nwas in cash in a currency that rounds cash payments (such as, `CAD` or `AUD`).", "readOnly": true, "required": false }, { "name": "rounding_adjustment_included_money", "type": "#/components/schemas/Money", "description": "If the most recent payment was a cash payment \nin a currency that rounds cash payments (such as, `CAD` or `AUD`) and the payment \nis rounded from `computed_amount_money` in the payment request, then this \nfield specifies the rounding adjustment applied. This amount \nmight be negative.", "readOnly": true, "required": false } ] }, { "name": "InvoiceRequestMethod", "properties": [] }, { "name": "InvoiceRequestType", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "InvoiceAutomaticPaymentSource", "properties": [] }, { "name": "InvoicePaymentReminder", "properties": [ { "name": "uid", "type": "string", "description": "A Square-assigned ID that uniquely identifies the reminder within the\n`InvoicePaymentRequest`.", "readOnly": true, "required": false }, { "name": "relative_scheduled_days", "type": "integer", "description": "The number of days before (a negative number) or after (a positive number)\nthe payment request `due_date` when the reminder is sent. For example, -3 indicates that\nthe reminder should be sent 3 days before the payment request `due_date`.", "readOnly": false, "required": false }, { "name": "message", "type": "string", "description": "The reminder message.", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/InvoicePaymentReminderStatus", "description": "The status of the reminder.\n", "readOnly": true, "required": false }, { "name": "sent_at", "type": "string", "description": "If sent, the timestamp when the reminder was sent, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "InvoicePaymentReminderStatus", "properties": [] }, { "name": "InvoiceDeliveryMethod", "properties": [] }, { "name": "InvoiceStatus", "properties": [] }, { "name": "InvoiceAcceptedPaymentMethods", "properties": [ { "name": "card", "type": "boolean", "description": "Indicates whether credit card or debit card payments are accepted. The default value is `false`.", "readOnly": false, "required": false }, { "name": "square_gift_card", "type": "boolean", "description": "Indicates whether Square gift card payments are accepted. The default value is `false`.", "readOnly": false, "required": false }, { "name": "bank_account", "type": "boolean", "description": "Indicates whether ACH bank transfer payments are accepted. The default value is `false`.", "readOnly": false, "required": false }, { "name": "buy_now_pay_later", "type": "boolean", "description": "Indicates whether Afterpay (also known as Clearpay) payments are accepted. The default value is `false`.\n\nThis option is allowed only for invoices that have a single payment request of the `BALANCE` type. This payment method is\nsupported if the seller account accepts Afterpay payments and the seller location is in a country where Afterpay\ninvoice payments are supported. As a best practice, consider enabling an additional payment method when allowing\n`buy_now_pay_later` payments. For more information, including detailed requirements and processing limits, see\n[Buy Now Pay Later payments with Afterpay](https://developer.squareup.com/docs/invoices-api/overview#buy-now-pay-later).", "readOnly": false, "required": false }, { "name": "cash_app_pay", "type": "boolean", "description": "Indicates whether Cash App payments are accepted. The default value is `false`.\n\nThis payment method is supported only for seller [locations](entity:Location) in the United States.", "readOnly": false, "required": false } ] }, { "name": "InvoiceCustomField", "properties": [ { "name": "label", "type": "string", "description": "The label or title of the custom field. This field is required for a custom field.", "readOnly": false, "required": false }, { "name": "value", "type": "string", "description": "The text of the custom field. If omitted, only the label is rendered.", "readOnly": false, "required": false }, { "name": "placement", "type": "#/components/schemas/InvoiceCustomFieldPlacement", "description": "The location of the custom field on the invoice. This field is required for a custom field.\n", "readOnly": false, "required": false } ] }, { "name": "InvoiceCustomFieldPlacement", "properties": [] }, { "name": "InvoiceAttachment", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the attachment.", "readOnly": true, "required": false }, { "name": "filename", "type": "string", "description": "The file name of the attachment, which is displayed on the invoice.", "readOnly": true, "required": false }, { "name": "description", "type": "string", "description": "The description of the attachment, which is displayed on the invoice.\nThis field maps to the seller-defined **Message** field.", "readOnly": true, "required": false }, { "name": "filesize", "type": "integer", "description": "The file size of the attachment in bytes.", "readOnly": true, "required": false }, { "name": "hash", "type": "string", "description": "The MD5 hash that was generated from the file contents.", "readOnly": true, "required": false }, { "name": "mime_type", "type": "string", "description": "The mime type of the attachment.\nThe following mime types are supported: \nimage/gif, image/jpeg, image/png, image/tiff, image/bmp, application/pdf.", "readOnly": true, "required": false }, { "name": "uploaded_at", "type": "string", "description": "The timestamp when the attachment was uploaded, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "CreateInvoiceAttachmentRequest": [ { "name": "CreateInvoiceAttachmentRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies the `CreateInvoiceAttachment` request.\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The description of the attachment to display on the invoice.", "readOnly": false, "required": false }, { "name": "invoice_id", "type": "string", "description": "The ID of the [invoice](entity:Invoice) to attach the file to.", "readOnly": false, "required": true } ] } ], "DeleteInvoiceAttachmentRequest": [ { "name": "DeleteInvoiceAttachmentRequest", "properties": [ { "name": "invoice_id", "type": "string", "description": "The ID of the [invoice](entity:Invoice) to delete the attachment from.", "readOnly": false, "required": true }, { "name": "attachment_id", "type": "string", "description": "The ID of the [attachment](entity:InvoiceAttachment) to delete.", "readOnly": false, "required": true } ] } ], "CancelInvoiceRequest": [ { "name": "CancelInvoiceRequest", "properties": [ { "name": "version", "type": "integer", "description": "The version of the [invoice](entity:Invoice) to cancel.\nIf you do not know the version, you can call \n[GetInvoice](api-endpoint:Invoices-GetInvoice) or [ListInvoices](api-endpoint:Invoices-ListInvoices).", "readOnly": false, "required": true }, { "name": "invoice_id", "type": "string", "description": "The ID of the [invoice](entity:Invoice) to cancel.", "readOnly": false, "required": true } ] } ], "PublishInvoiceRequest": [ { "name": "PublishInvoiceRequest", "properties": [ { "name": "version", "type": "integer", "description": "The version of the [invoice](entity:Invoice) to publish.\nThis must match the current version of the invoice; otherwise, the request is rejected.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies the `PublishInvoice` request. If you do not \nprovide `idempotency_key` (or provide an empty string as the value), the endpoint \ntreats each request as independent.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "invoice_id", "type": "string", "description": "The ID of the invoice to publish.", "readOnly": false, "required": true } ] } ], "ListBreakTypesRequest": [ { "name": "ListBreakTypesRequest", "properties": [ { "name": "location_id", "type": "string", "description": "Filter the returned `BreakType` results to only those that are associated with the\nspecified location.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of `BreakType` results to return per page. The number can range between 1\nand 200. The default is 200.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pointer to the next page of `BreakType` results to fetch.", "readOnly": false, "required": false } ] } ], "CreateBreakTypeRequest": [ { "name": "CreateBreakTypeRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string value to ensure the idempotency of the operation.", "readOnly": false, "required": false }, { "name": "break_type", "type": "#/components/schemas/BreakType", "description": "The `BreakType` to be created.", "readOnly": false, "required": true } ] }, { "name": "BreakType", "properties": [ { "name": "id", "type": "string", "description": "The UUID for this object.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the business location this type of break applies to.", "readOnly": false, "required": true }, { "name": "break_name", "type": "string", "description": "A human-readable name for this type of break. The name is displayed to\nemployees in Square products.", "readOnly": false, "required": true }, { "name": "expected_duration", "type": "string", "description": "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthis break. Precision less than minutes is truncated.\n\nExample for break expected duration of 15 minutes: T15M", "readOnly": false, "required": true }, { "name": "is_paid", "type": "boolean", "description": "Whether this break counts towards time worked for compensation\npurposes.", "readOnly": false, "required": true }, { "name": "version", "type": "integer", "description": "Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If a value is not\nprovided, Square's servers execute a \"blind\" write; potentially\noverwriting another writer's data.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "A read-only timestamp in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "A read-only timestamp in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "DeleteBreakTypeRequest": [ { "name": "DeleteBreakTypeRequest", "properties": [ { "name": "id", "type": "string", "description": "The UUID for the `BreakType` being deleted.", "readOnly": false, "required": true } ] } ], "GetBreakTypeRequest": [ { "name": "GetBreakTypeRequest", "properties": [ { "name": "id", "type": "string", "description": "The UUID for the `BreakType` being retrieved.", "readOnly": false, "required": true } ] } ], "UpdateBreakTypeRequest": [ { "name": "UpdateBreakTypeRequest", "properties": [ { "name": "break_type", "type": "#/components/schemas/BreakType", "description": "The updated `BreakType`.", "readOnly": false, "required": true }, { "name": "id", "type": "string", "description": " The UUID for the `BreakType` being updated.", "readOnly": false, "required": true } ] }, { "name": "BreakType", "properties": [ { "name": "id", "type": "string", "description": "The UUID for this object.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the business location this type of break applies to.", "readOnly": false, "required": true }, { "name": "break_name", "type": "string", "description": "A human-readable name for this type of break. The name is displayed to\nemployees in Square products.", "readOnly": false, "required": true }, { "name": "expected_duration", "type": "string", "description": "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthis break. Precision less than minutes is truncated.\n\nExample for break expected duration of 15 minutes: T15M", "readOnly": false, "required": true }, { "name": "is_paid", "type": "boolean", "description": "Whether this break counts towards time worked for compensation\npurposes.", "readOnly": false, "required": true }, { "name": "version", "type": "integer", "description": "Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If a value is not\nprovided, Square's servers execute a \"blind\" write; potentially\noverwriting another writer's data.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "A read-only timestamp in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "A read-only timestamp in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "CreateShiftRequest": [ { "name": "CreateShiftRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string value to ensure the idempotency of the operation.", "readOnly": false, "required": false }, { "name": "shift", "type": "#/components/schemas/Shift", "description": "The `Shift` to be created.", "readOnly": false, "required": true } ] }, { "name": "Shift", "properties": [ { "name": "id", "type": "string", "description": "The UUID for this object.", "readOnly": false, "required": false }, { "name": "employee_id", "type": "string", "description": "The ID of the employee this shift belongs to. DEPRECATED at version 2020-08-26. Use `team_member_id` instead.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the location this shift occurred at. The location should be based on\nwhere the employee clocked in.", "readOnly": false, "required": true }, { "name": "timezone", "type": "string", "description": "The read-only convenience value that is calculated from the location based\non the `location_id`. Format: the IANA timezone database identifier for the\nlocation timezone.", "readOnly": false, "required": false }, { "name": "start_at", "type": "string", "description": "RFC 3339; shifted to the location timezone + offset. Precision up to the\nminute is respected; seconds are truncated.", "readOnly": false, "required": true }, { "name": "end_at", "type": "string", "description": "RFC 3339; shifted to the timezone + offset. Precision up to the minute is\nrespected; seconds are truncated.", "readOnly": false, "required": false }, { "name": "wage", "type": "#/components/schemas/ShiftWage", "description": "Job and pay related information. If the wage is not set on create, it defaults to a wage\nof zero. If the title is not set on create, it defaults to the name of the role the employee\nis assigned to, if any.", "readOnly": false, "required": false }, { "name": "breaks", "type": "array", "description": "A list of all the paid or unpaid breaks that were taken during this shift.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Break" }, { "name": "status", "type": "#/components/schemas/ShiftStatus", "description": "Describes the working state of the current `Shift`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If not provided,\nSquare executes a blind write; potentially overwriting data from another\nwrite.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "A read-only timestamp in RFC 3339 format; presented in UTC.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "A read-only timestamp in RFC 3339 format; presented in UTC.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "team_member_id", "type": "string", "description": "The ID of the team member this shift belongs to. Replaced `employee_id` at version \"2020-08-26\".", "readOnly": false, "required": false }, { "name": "declared_cash_tip_money", "type": "#/components/schemas/Money", "description": "The tips declared by the team member for the shift.", "readOnly": false, "required": false } ] }, { "name": "ShiftWage", "properties": [ { "name": "title", "type": "string", "description": "The name of the job performed during this shift.", "readOnly": false, "required": false }, { "name": "hourly_rate", "type": "#/components/schemas/Money", "description": "Can be a custom-set hourly wage or the calculated effective hourly\nwage based on the annual wage and hours worked per week.", "readOnly": false, "required": false }, { "name": "job_id", "type": "string", "description": "The id of the job performed during this shift. Square\nlabor-reporting UIs might group shifts together by id. This cannot be used to retrieve the job.", "readOnly": true, "required": false }, { "name": "tip_eligible", "type": "boolean", "description": "Whether team members are eligible for tips when working this job.", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "Break", "properties": [ { "name": "id", "type": "string", "description": "The UUID for this object.", "readOnly": false, "required": false }, { "name": "start_at", "type": "string", "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated.", "readOnly": false, "required": true }, { "name": "end_at", "type": "string", "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated.", "readOnly": false, "required": false }, { "name": "break_type_id", "type": "string", "description": "The `BreakType` that this `Break` was templated on.", "readOnly": false, "required": true }, { "name": "name", "type": "string", "description": "A human-readable name.", "readOnly": false, "required": true }, { "name": "expected_duration", "type": "string", "description": "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthe break.", "readOnly": false, "required": true }, { "name": "is_paid", "type": "boolean", "description": "Whether this break counts towards time worked for compensation\npurposes.", "readOnly": false, "required": true } ] }, { "name": "ShiftStatus", "properties": [] } ], "SearchShiftsRequest": [ { "name": "SearchShiftsRequest", "properties": [ { "name": "query", "type": "#/components/schemas/ShiftQuery", "description": "Query filters.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The number of resources in a page (200 by default).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "An opaque cursor for fetching the next page.", "readOnly": false, "required": false } ] }, { "name": "ShiftQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/ShiftFilter", "description": "Query filter options.", "readOnly": false, "required": false }, { "name": "sort", "type": "#/components/schemas/ShiftSort", "description": "Sort order details.", "readOnly": false, "required": false } ] }, { "name": "ShiftFilter", "properties": [ { "name": "location_ids", "type": "array", "description": "Fetch shifts for the specified location.", "readOnly": false, "required": false }, { "name": "employee_ids", "type": "array", "description": "Fetch shifts for the specified employees. DEPRECATED at version 2020-08-26. Use `team_member_ids` instead.", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/ShiftFilterStatus", "description": "Fetch a `Shift` instance by `Shift.status`.\n", "readOnly": false, "required": false }, { "name": "start", "type": "#/components/schemas/TimeRange", "description": "Fetch `Shift` instances that start in the time range - Inclusive.", "readOnly": false, "required": false }, { "name": "end", "type": "#/components/schemas/TimeRange", "description": "Fetch the `Shift` instances that end in the time range - Inclusive.", "readOnly": false, "required": false }, { "name": "workday", "type": "#/components/schemas/ShiftWorkday", "description": "Fetch the `Shift` instances based on the workday date range.", "readOnly": false, "required": false }, { "name": "team_member_ids", "type": "array", "description": "Fetch shifts for the specified team members. Replaced `employee_ids` at version \"2020-08-26\".", "readOnly": false, "required": false } ] }, { "name": "ShiftFilterStatus", "properties": [] }, { "name": "TimeRange", "properties": [ { "name": "start_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nstarts.", "readOnly": false, "required": false }, { "name": "end_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nends.", "readOnly": false, "required": false } ] }, { "name": "ShiftWorkday", "properties": [ { "name": "date_range", "type": "#/components/schemas/DateRange", "description": "Dates for fetching the shifts.", "readOnly": false, "required": false }, { "name": "match_shifts_by", "type": "#/components/schemas/ShiftWorkdayMatcher", "description": "The strategy on which the dates are applied.\n", "readOnly": false, "required": false }, { "name": "default_timezone", "type": "string", "description": "Location-specific timezones convert workdays to datetime filters.\nEvery location included in the query must have a timezone or this field\nmust be provided as a fallback. Format: the IANA timezone database\nidentifier for the relevant timezone.", "readOnly": false, "required": false } ] }, { "name": "DateRange", "properties": [ { "name": "start_date", "type": "string", "description": "A string in `YYYY-MM-DD` format, such as `2017-10-31`, per the ISO 8601\nextended format for calendar dates.\nThe beginning of a date range (inclusive).", "readOnly": false, "required": false }, { "name": "end_date", "type": "string", "description": "A string in `YYYY-MM-DD` format, such as `2017-10-31`, per the ISO 8601\nextended format for calendar dates.\nThe end of a date range (inclusive).", "readOnly": false, "required": false } ] }, { "name": "ShiftWorkdayMatcher", "properties": [] }, { "name": "ShiftSort", "properties": [ { "name": "field", "type": "#/components/schemas/ShiftSortField", "description": "The field to sort on.\n", "readOnly": false, "required": false }, { "name": "order", "type": "#/components/schemas/SortOrder", "description": "The order in which results are returned. Defaults to DESC.\n", "readOnly": false, "required": false } ] }, { "name": "ShiftSortField", "properties": [] }, { "name": "SortOrder", "properties": [] } ], "DeleteShiftRequest": [ { "name": "DeleteShiftRequest", "properties": [ { "name": "id", "type": "string", "description": "The UUID for the `Shift` being deleted.", "readOnly": false, "required": true } ] } ], "GetShiftRequest": [ { "name": "GetShiftRequest", "properties": [ { "name": "id", "type": "string", "description": "The UUID for the `Shift` being retrieved.", "readOnly": false, "required": true } ] } ], "UpdateShiftRequest": [ { "name": "UpdateShiftRequest", "properties": [ { "name": "shift", "type": "#/components/schemas/Shift", "description": "The updated `Shift` object.", "readOnly": false, "required": true }, { "name": "id", "type": "string", "description": "The ID of the object being updated.", "readOnly": false, "required": true } ] }, { "name": "Shift", "properties": [ { "name": "id", "type": "string", "description": "The UUID for this object.", "readOnly": false, "required": false }, { "name": "employee_id", "type": "string", "description": "The ID of the employee this shift belongs to. DEPRECATED at version 2020-08-26. Use `team_member_id` instead.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the location this shift occurred at. The location should be based on\nwhere the employee clocked in.", "readOnly": false, "required": true }, { "name": "timezone", "type": "string", "description": "The read-only convenience value that is calculated from the location based\non the `location_id`. Format: the IANA timezone database identifier for the\nlocation timezone.", "readOnly": false, "required": false }, { "name": "start_at", "type": "string", "description": "RFC 3339; shifted to the location timezone + offset. Precision up to the\nminute is respected; seconds are truncated.", "readOnly": false, "required": true }, { "name": "end_at", "type": "string", "description": "RFC 3339; shifted to the timezone + offset. Precision up to the minute is\nrespected; seconds are truncated.", "readOnly": false, "required": false }, { "name": "wage", "type": "#/components/schemas/ShiftWage", "description": "Job and pay related information. If the wage is not set on create, it defaults to a wage\nof zero. If the title is not set on create, it defaults to the name of the role the employee\nis assigned to, if any.", "readOnly": false, "required": false }, { "name": "breaks", "type": "array", "description": "A list of all the paid or unpaid breaks that were taken during this shift.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Break" }, { "name": "status", "type": "#/components/schemas/ShiftStatus", "description": "Describes the working state of the current `Shift`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If not provided,\nSquare executes a blind write; potentially overwriting data from another\nwrite.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "A read-only timestamp in RFC 3339 format; presented in UTC.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "A read-only timestamp in RFC 3339 format; presented in UTC.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "team_member_id", "type": "string", "description": "The ID of the team member this shift belongs to. Replaced `employee_id` at version \"2020-08-26\".", "readOnly": false, "required": false }, { "name": "declared_cash_tip_money", "type": "#/components/schemas/Money", "description": "The tips declared by the team member for the shift.", "readOnly": false, "required": false } ] }, { "name": "ShiftWage", "properties": [ { "name": "title", "type": "string", "description": "The name of the job performed during this shift.", "readOnly": false, "required": false }, { "name": "hourly_rate", "type": "#/components/schemas/Money", "description": "Can be a custom-set hourly wage or the calculated effective hourly\nwage based on the annual wage and hours worked per week.", "readOnly": false, "required": false }, { "name": "job_id", "type": "string", "description": "The id of the job performed during this shift. Square\nlabor-reporting UIs might group shifts together by id. This cannot be used to retrieve the job.", "readOnly": true, "required": false }, { "name": "tip_eligible", "type": "boolean", "description": "Whether team members are eligible for tips when working this job.", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "Break", "properties": [ { "name": "id", "type": "string", "description": "The UUID for this object.", "readOnly": false, "required": false }, { "name": "start_at", "type": "string", "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated.", "readOnly": false, "required": true }, { "name": "end_at", "type": "string", "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated.", "readOnly": false, "required": false }, { "name": "break_type_id", "type": "string", "description": "The `BreakType` that this `Break` was templated on.", "readOnly": false, "required": true }, { "name": "name", "type": "string", "description": "A human-readable name.", "readOnly": false, "required": true }, { "name": "expected_duration", "type": "string", "description": "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthe break.", "readOnly": false, "required": true }, { "name": "is_paid", "type": "boolean", "description": "Whether this break counts towards time worked for compensation\npurposes.", "readOnly": false, "required": true } ] }, { "name": "ShiftStatus", "properties": [] } ], "ListTeamMemberWagesRequest": [ { "name": "ListTeamMemberWagesRequest", "properties": [ { "name": "team_member_id", "type": "string", "description": "Filter the returned wages to only those that are associated with the\nspecified team member.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of `TeamMemberWage` results to return per page. The number can range between\n1 and 200. The default is 200.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pointer to the next page of `EmployeeWage` results to fetch.", "readOnly": false, "required": false } ] } ], "GetTeamMemberWageRequest": [ { "name": "GetTeamMemberWageRequest", "properties": [ { "name": "id", "type": "string", "description": "The UUID for the `TeamMemberWage` being retrieved.", "readOnly": false, "required": true } ] } ], "ListWorkweekConfigsRequest": [ { "name": "ListWorkweekConfigsRequest", "properties": [ { "name": "limit", "type": "integer", "description": "The maximum number of `WorkweekConfigs` results to return per page.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pointer to the next page of `WorkweekConfig` results to fetch.", "readOnly": false, "required": false } ] } ], "UpdateWorkweekConfigRequest": [ { "name": "UpdateWorkweekConfigRequest", "properties": [ { "name": "workweek_config", "type": "#/components/schemas/WorkweekConfig", "description": "The updated `WorkweekConfig` object.", "readOnly": false, "required": true }, { "name": "id", "type": "string", "description": "The UUID for the `WorkweekConfig` object being updated.", "readOnly": false, "required": true } ] }, { "name": "WorkweekConfig", "properties": [ { "name": "id", "type": "string", "description": "The UUID for this object.", "readOnly": false, "required": false }, { "name": "start_of_week", "type": "#/components/schemas/Weekday", "description": "The day of the week on which a business week starts for\ncompensation purposes.\n", "readOnly": false, "required": true }, { "name": "start_of_day_local_time", "type": "string", "description": "The local time at which a business week starts. Represented as a\nstring in `HH:MM` format (`HH:MM:SS` is also accepted, but seconds are\ntruncated).", "readOnly": false, "required": true }, { "name": "version", "type": "integer", "description": "Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If not provided,\nSquare executes a blind write; potentially overwriting data from another\nwrite.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "A read-only timestamp in RFC 3339 format; presented in UTC.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "A read-only timestamp in RFC 3339 format; presented in UTC.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "Weekday", "properties": [] } ], "ListLocationCustomAttributeDefinitionsRequest": [ { "name": "ListLocationCustomAttributeDefinitionsRequest", "properties": [ { "name": "visibility_filter", "type": "#/components/schemas/VisibilityFilter", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.\n", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] }, { "name": "VisibilityFilter", "properties": [] } ], "CreateLocationCustomAttributeDefinitionRequest": [ { "name": "CreateLocationCustomAttributeDefinitionRequest", "properties": [ { "name": "custom_attribute_definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "The custom attribute definition to create. Note the following:\n- With the exception of the `Selection` data type, the `schema` is specified as a simple URL to the JSON schema\ndefinition hosted on the Square CDN. For more information, including supported values and constraints, see\n[Supported data types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types).\n- `name` is required unless `visibility` is set to `VISIBILITY_HIDDEN`.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false } ] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] } ], "DeleteLocationCustomAttributeDefinitionRequest": [ { "name": "DeleteLocationCustomAttributeDefinitionRequest", "properties": [ { "name": "key", "type": "string", "description": "The key of the custom attribute definition to delete.", "readOnly": false, "required": true } ] } ], "RetrieveLocationCustomAttributeDefinitionRequest": [ { "name": "RetrieveLocationCustomAttributeDefinitionRequest", "properties": [ { "name": "version", "type": "integer", "description": "The current version of the custom attribute definition, which is used for strongly consistent\nreads to guarantee that you receive the most up-to-date data. When included in the request,\nSquare returns the specified version or a higher version if one exists. If the specified version\nis higher than the current version, Square returns a `BAD_REQUEST` error.", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "The key of the custom attribute definition to retrieve. If the requesting application\nis not the definition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "UpdateLocationCustomAttributeDefinitionRequest": [ { "name": "UpdateLocationCustomAttributeDefinitionRequest", "properties": [ { "name": "custom_attribute_definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "The custom attribute definition that contains the fields to update. This endpoint\nsupports sparse updates, so only new or changed fields need to be included in the request.\nOnly the following fields can be updated:\n- `name`\n- `description`\n- `visibility`\n- `schema` for a `Selection` data type. Only changes to the named options or the maximum number of allowed\nselections are supported.\n\nFor more information, see\n[Update a location custom attribute definition](https://developer.squareup.com/docs/location-custom-attributes-api/custom-attribute-definitions#update-custom-attribute-definition).\nTo enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol, specify the current version of the custom attribute definition. \nIf this is not important for your application, `version` can be set to -1.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "The key of the custom attribute definition to update.", "readOnly": false, "required": true } ] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] } ], "BulkDeleteLocationCustomAttributesRequest": [ { "name": "BulkDeleteLocationCustomAttributesRequest", "properties": [ { "name": "values", "type": "map", "description": "The data used to update the `CustomAttribute` objects.\nThe keys must be unique and are used to map to the corresponding response.", "readOnly": false, "required": true } ] } ], "BulkUpsertLocationCustomAttributesRequest": [ { "name": "BulkUpsertLocationCustomAttributesRequest", "properties": [ { "name": "values", "type": "map", "description": "A map containing 1 to 25 individual upsert requests. For each request, provide an\narbitrary ID that is unique for this `BulkUpsertLocationCustomAttributes` request and the\ninformation needed to create or update a custom attribute.", "readOnly": false, "required": true } ] } ], "ListLocationCustomAttributesRequest": [ { "name": "ListLocationCustomAttributesRequest", "properties": [ { "name": "visibility_filter", "type": "#/components/schemas/VisibilityFilter", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.\n", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request. For more\ninformation, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "with_definitions", "type": "boolean", "description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each\ncustom attribute. Set this parameter to `true` to get the name and description of each custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the target [location](entity:Location).", "readOnly": false, "required": true } ] }, { "name": "VisibilityFilter", "properties": [] } ], "DeleteLocationCustomAttributeRequest": [ { "name": "DeleteLocationCustomAttributeRequest", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the target [location](entity:Location).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to delete. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "RetrieveLocationCustomAttributeRequest": [ { "name": "RetrieveLocationCustomAttributeRequest", "properties": [ { "name": "with_definition", "type": "boolean", "description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of\nthe custom attribute. Set this parameter to `true` to get the name and description of the custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The current version of the custom attribute, which is used for strongly consistent reads to\nguarantee that you receive the most up-to-date data. When included in the request, Square\nreturns the specified version or a higher version if one exists. If the specified version is\nhigher than the current version, Square returns a `BAD_REQUEST` error.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the target [location](entity:Location).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to retrieve. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "UpsertLocationCustomAttributeRequest": [ { "name": "UpsertLocationCustomAttributeRequest", "properties": [ { "name": "custom_attribute", "type": "#/components/schemas/CustomAttribute", "description": "The custom attribute to create or update, with the following fields:\n- `value`. This value must conform to the `schema` specified by the definition.\nFor more information, see [Supported data types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types).\n- `version`. To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol for an update operation, include the current version of the custom attribute.\nIf this is not important for your application, version can be set to -1.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the target [location](entity:Location).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to create or update. This key must match the `key` of a\ncustom attribute definition in the Square seller account. If the requesting application is not\nthe definition owner, you must use the qualified key.", "readOnly": false, "required": true } ] }, { "name": "CustomAttribute", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).", "readOnly": false, "required": false }, { "name": "value", "type": "string", "description": "The value assigned to the custom attribute. It is validated against the custom\nattribute definition's schema on write operations. For more information about custom\nattribute values,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute. This field is incremented when the custom attribute is changed.\nWhen updating an existing custom attribute value, you can provide this field\nand specify the current version of the custom attribute to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "A copy of the `visibility` field value for the associated custom attribute definition.\n", "readOnly": true, "required": false }, { "name": "definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "A copy of the associated custom attribute definition object. This field is only set when\nthe optional field is specified on the request.", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute was created or was most recently\nupdated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "ListLocationsRequest": [ { "name": "ListLocationsRequest", "properties": [] } ], "CreateLocationRequest": [ { "name": "CreateLocationRequest", "properties": [ { "name": "location", "type": "#/components/schemas/Location", "description": "The initial values of the location being created. The `name` field is required and must be unique within a seller account.\nAll other fields are optional, but any information you care about for the location should be included.\nThe remaining fields are automatically added based on the data from the [main location](https://developer.squareup.com/docs/locations-api#about-the-main-location).", "readOnly": false, "required": false } ] }, { "name": "Location", "properties": [ { "name": "id", "type": "string", "description": "A short generated string of letters and numbers that uniquely identifies this location instance.", "readOnly": true, "required": false }, { "name": "name", "type": "string", "description": "The name of the location.\nThis information appears in the Seller Dashboard as the nickname.\nA location name must be unique within a seller account.", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The physical address of the location.", "readOnly": false, "required": false }, { "name": "timezone", "type": "string", "description": "The [IANA time zone](https://www.iana.org/time-zones) identifier for\nthe time zone of the location. For example, `America/Los_Angeles`.", "readOnly": false, "required": false }, { "name": "capabilities", "type": "array", "description": "The Square features that are enabled for the location.\n\n", "readOnly": true, "required": false, "arrayType": "#/components/schemas/LocationCapability" }, { "name": "status", "type": "#/components/schemas/LocationStatus", "description": "The status of the location.\n", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The time when the location was created, in RFC 3339 format.\nFor more information, see [Working with Dates](https://developer.squareup.com/docs/build-basics/working-with-dates).", "readOnly": true, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the merchant that owns the location.", "readOnly": true, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The country of the location, in the two-letter format of ISO 3166. For example, `US` or `JP`.\n\n\n", "readOnly": true, "required": false }, { "name": "language_code", "type": "string", "description": "The language associated with the location, in\n[BCP 47 format](https://tools.ietf.org/html/bcp47#appendix-A).\nFor more information, see [Language Preferences](https://developer.squareup.com/docs/build-basics/general-considerations/language-preferences).", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The currency used for all transactions at this location,\nin ISO 4217 format. For example, the currency code for US dollars is `USD`.\n\n", "readOnly": true, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number of the location. For example, `+1 855-700-6000`.", "readOnly": false, "required": false }, { "name": "business_name", "type": "string", "description": "The name of the location's overall business. This name is present on receipts and other customer-facing branding, and can be changed no more than three times in a twelve-month period.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/LocationType", "description": "The type of the location.\n", "readOnly": false, "required": false }, { "name": "website_url", "type": "string", "description": "The website URL of the location. For example, `https://squareup.com`.", "readOnly": false, "required": false }, { "name": "business_hours", "type": "#/components/schemas/BusinessHours", "description": "The hours of operation for the location.", "readOnly": false, "required": false }, { "name": "business_email", "type": "string", "description": "The email address of the location. This can be unique to the location and is not always the email address for the business owner or administrator.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The description of the location. For example, `Main Street location`.", "readOnly": false, "required": false }, { "name": "twitter_username", "type": "string", "description": "The Twitter username of the location without the '@' symbol. For example, `Square`.", "readOnly": false, "required": false }, { "name": "instagram_username", "type": "string", "description": "The Instagram username of the location without the '@' symbol. For example, `square`.", "readOnly": false, "required": false }, { "name": "facebook_url", "type": "string", "description": "The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. For example, `https://www.facebook.com/square`.", "readOnly": false, "required": false }, { "name": "coordinates", "type": "#/components/schemas/Coordinates", "description": "The physical coordinates (latitude and longitude) of the location.", "readOnly": false, "required": false }, { "name": "logo_url", "type": "string", "description": "The URL of the logo image for the location. When configured in the Seller\nDashboard (Receipts section), the logo appears on transactions (such as receipts and invoices) that Square generates on behalf of the seller.\nThis image should have a roughly square (1:1) aspect ratio and should be at least 200x200 pixels.", "readOnly": true, "required": false }, { "name": "pos_background_url", "type": "string", "description": "The URL of the Point of Sale background image for the location.", "readOnly": true, "required": false }, { "name": "mcc", "type": "string", "description": "A four-digit number that describes the kind of goods or services sold at the location.\nThe [merchant category code (MCC)](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) of the location as standardized by ISO 18245.\nFor example, `5045`, for a location that sells computer goods and software.", "readOnly": false, "required": false }, { "name": "full_format_logo_url", "type": "string", "description": "The URL of a full-format logo image for the location. When configured in the Seller\nDashboard (Receipts section), the logo appears on transactions (such as receipts and invoices) that Square generates on behalf of the seller.\nThis image can be wider than it is tall and should be at least 1280x648 pixels.", "readOnly": true, "required": false }, { "name": "tax_ids", "type": "#/components/schemas/TaxIds", "description": "The tax IDs for this location.", "readOnly": true, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "LocationCapability", "properties": [] }, { "name": "LocationStatus", "properties": [] }, { "name": "Currency", "properties": [] }, { "name": "LocationType", "properties": [] }, { "name": "BusinessHours", "properties": [ { "name": "periods", "type": "array", "description": "The list of time periods during which the business is open. There can be at most 10 periods per day.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/BusinessHoursPeriod" } ] }, { "name": "BusinessHoursPeriod", "properties": [ { "name": "day_of_week", "type": "#/components/schemas/DayOfWeek", "description": "The day of the week for this time period.\n", "readOnly": false, "required": false }, { "name": "start_local_time", "type": "string", "description": "The start time of a business hours period, specified in local time using partial-time\nRFC 3339 format. For example, `8:30:00` for a period starting at 8:30 in the morning.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC.", "readOnly": false, "required": false }, { "name": "end_local_time", "type": "string", "description": "The end time of a business hours period, specified in local time using partial-time\nRFC 3339 format. For example, `21:00:00` for a period ending at 9:00 in the evening.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC.", "readOnly": false, "required": false } ] }, { "name": "DayOfWeek", "properties": [] }, { "name": "Coordinates", "properties": [ { "name": "latitude", "type": "number", "description": "The latitude of the coordinate expressed in degrees.", "readOnly": false, "required": false }, { "name": "longitude", "type": "number", "description": "The longitude of the coordinate expressed in degrees.", "readOnly": false, "required": false } ] }, { "name": "TaxIds", "properties": [ { "name": "eu_vat", "type": "string", "description": "The EU VAT number for this location. For example, `IE3426675K`.\nIf the EU VAT number is present, it is well-formed and has been\nvalidated with VIES, the VAT Information Exchange System.", "readOnly": true, "required": false }, { "name": "fr_siret", "type": "string", "description": "The SIRET (Système d'Identification du Répertoire des Entreprises et de leurs Etablissements)\nnumber is a 14-digit code issued by the French INSEE. For example, `39922799000021`.", "readOnly": true, "required": false }, { "name": "fr_naf", "type": "string", "description": "The French government uses the NAF (Nomenclature des Activités Françaises) to display and\ntrack economic statistical data. This is also called the APE (Activite Principale de l’Entreprise) code.\nFor example, `6910Z`.", "readOnly": true, "required": false }, { "name": "es_nif", "type": "string", "description": "The NIF (Numero de Identificacion Fiscal) number is a nine-character tax identifier used in Spain.\nIf it is present, it has been validated. For example, `73628495A`.", "readOnly": true, "required": false }, { "name": "jp_qii", "type": "string", "description": "The QII (Qualified Invoice Issuer) number is a 14-character tax identifier used in Japan.\nFor example, `T1234567890123`.", "readOnly": true, "required": false } ] } ], "RetrieveLocationRequest": [ { "name": "RetrieveLocationRequest", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the location to retrieve. Specify the string\n\"main\" to return the main location.", "readOnly": false, "required": true } ] } ], "UpdateLocationRequest": [ { "name": "UpdateLocationRequest", "properties": [ { "name": "location", "type": "#/components/schemas/Location", "description": "The `Location` object with only the fields to update.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the location to update.", "readOnly": false, "required": true } ] }, { "name": "Location", "properties": [ { "name": "id", "type": "string", "description": "A short generated string of letters and numbers that uniquely identifies this location instance.", "readOnly": true, "required": false }, { "name": "name", "type": "string", "description": "The name of the location.\nThis information appears in the Seller Dashboard as the nickname.\nA location name must be unique within a seller account.", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The physical address of the location.", "readOnly": false, "required": false }, { "name": "timezone", "type": "string", "description": "The [IANA time zone](https://www.iana.org/time-zones) identifier for\nthe time zone of the location. For example, `America/Los_Angeles`.", "readOnly": false, "required": false }, { "name": "capabilities", "type": "array", "description": "The Square features that are enabled for the location.\n\n", "readOnly": true, "required": false, "arrayType": "#/components/schemas/LocationCapability" }, { "name": "status", "type": "#/components/schemas/LocationStatus", "description": "The status of the location.\n", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The time when the location was created, in RFC 3339 format.\nFor more information, see [Working with Dates](https://developer.squareup.com/docs/build-basics/working-with-dates).", "readOnly": true, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the merchant that owns the location.", "readOnly": true, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The country of the location, in the two-letter format of ISO 3166. For example, `US` or `JP`.\n\n\n", "readOnly": true, "required": false }, { "name": "language_code", "type": "string", "description": "The language associated with the location, in\n[BCP 47 format](https://tools.ietf.org/html/bcp47#appendix-A).\nFor more information, see [Language Preferences](https://developer.squareup.com/docs/build-basics/general-considerations/language-preferences).", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The currency used for all transactions at this location,\nin ISO 4217 format. For example, the currency code for US dollars is `USD`.\n\n", "readOnly": true, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number of the location. For example, `+1 855-700-6000`.", "readOnly": false, "required": false }, { "name": "business_name", "type": "string", "description": "The name of the location's overall business. This name is present on receipts and other customer-facing branding, and can be changed no more than three times in a twelve-month period.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/LocationType", "description": "The type of the location.\n", "readOnly": false, "required": false }, { "name": "website_url", "type": "string", "description": "The website URL of the location. For example, `https://squareup.com`.", "readOnly": false, "required": false }, { "name": "business_hours", "type": "#/components/schemas/BusinessHours", "description": "The hours of operation for the location.", "readOnly": false, "required": false }, { "name": "business_email", "type": "string", "description": "The email address of the location. This can be unique to the location and is not always the email address for the business owner or administrator.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "The description of the location. For example, `Main Street location`.", "readOnly": false, "required": false }, { "name": "twitter_username", "type": "string", "description": "The Twitter username of the location without the '@' symbol. For example, `Square`.", "readOnly": false, "required": false }, { "name": "instagram_username", "type": "string", "description": "The Instagram username of the location without the '@' symbol. For example, `square`.", "readOnly": false, "required": false }, { "name": "facebook_url", "type": "string", "description": "The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. For example, `https://www.facebook.com/square`.", "readOnly": false, "required": false }, { "name": "coordinates", "type": "#/components/schemas/Coordinates", "description": "The physical coordinates (latitude and longitude) of the location.", "readOnly": false, "required": false }, { "name": "logo_url", "type": "string", "description": "The URL of the logo image for the location. When configured in the Seller\nDashboard (Receipts section), the logo appears on transactions (such as receipts and invoices) that Square generates on behalf of the seller.\nThis image should have a roughly square (1:1) aspect ratio and should be at least 200x200 pixels.", "readOnly": true, "required": false }, { "name": "pos_background_url", "type": "string", "description": "The URL of the Point of Sale background image for the location.", "readOnly": true, "required": false }, { "name": "mcc", "type": "string", "description": "A four-digit number that describes the kind of goods or services sold at the location.\nThe [merchant category code (MCC)](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) of the location as standardized by ISO 18245.\nFor example, `5045`, for a location that sells computer goods and software.", "readOnly": false, "required": false }, { "name": "full_format_logo_url", "type": "string", "description": "The URL of a full-format logo image for the location. When configured in the Seller\nDashboard (Receipts section), the logo appears on transactions (such as receipts and invoices) that Square generates on behalf of the seller.\nThis image can be wider than it is tall and should be at least 1280x648 pixels.", "readOnly": true, "required": false }, { "name": "tax_ids", "type": "#/components/schemas/TaxIds", "description": "The tax IDs for this location.", "readOnly": true, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "LocationCapability", "properties": [] }, { "name": "LocationStatus", "properties": [] }, { "name": "Currency", "properties": [] }, { "name": "LocationType", "properties": [] }, { "name": "BusinessHours", "properties": [ { "name": "periods", "type": "array", "description": "The list of time periods during which the business is open. There can be at most 10 periods per day.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/BusinessHoursPeriod" } ] }, { "name": "BusinessHoursPeriod", "properties": [ { "name": "day_of_week", "type": "#/components/schemas/DayOfWeek", "description": "The day of the week for this time period.\n", "readOnly": false, "required": false }, { "name": "start_local_time", "type": "string", "description": "The start time of a business hours period, specified in local time using partial-time\nRFC 3339 format. For example, `8:30:00` for a period starting at 8:30 in the morning.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC.", "readOnly": false, "required": false }, { "name": "end_local_time", "type": "string", "description": "The end time of a business hours period, specified in local time using partial-time\nRFC 3339 format. For example, `21:00:00` for a period ending at 9:00 in the evening.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC.", "readOnly": false, "required": false } ] }, { "name": "DayOfWeek", "properties": [] }, { "name": "Coordinates", "properties": [ { "name": "latitude", "type": "number", "description": "The latitude of the coordinate expressed in degrees.", "readOnly": false, "required": false }, { "name": "longitude", "type": "number", "description": "The longitude of the coordinate expressed in degrees.", "readOnly": false, "required": false } ] }, { "name": "TaxIds", "properties": [ { "name": "eu_vat", "type": "string", "description": "The EU VAT number for this location. For example, `IE3426675K`.\nIf the EU VAT number is present, it is well-formed and has been\nvalidated with VIES, the VAT Information Exchange System.", "readOnly": true, "required": false }, { "name": "fr_siret", "type": "string", "description": "The SIRET (Système d'Identification du Répertoire des Entreprises et de leurs Etablissements)\nnumber is a 14-digit code issued by the French INSEE. For example, `39922799000021`.", "readOnly": true, "required": false }, { "name": "fr_naf", "type": "string", "description": "The French government uses the NAF (Nomenclature des Activités Françaises) to display and\ntrack economic statistical data. This is also called the APE (Activite Principale de l’Entreprise) code.\nFor example, `6910Z`.", "readOnly": true, "required": false }, { "name": "es_nif", "type": "string", "description": "The NIF (Numero de Identificacion Fiscal) number is a nine-character tax identifier used in Spain.\nIf it is present, it has been validated. For example, `73628495A`.", "readOnly": true, "required": false }, { "name": "jp_qii", "type": "string", "description": "The QII (Qualified Invoice Issuer) number is a 14-character tax identifier used in Japan.\nFor example, `T1234567890123`.", "readOnly": true, "required": false } ] } ], "CreateLoyaltyAccountRequest": [ { "name": "CreateLoyaltyAccountRequest", "properties": [ { "name": "loyalty_account", "type": "#/components/schemas/LoyaltyAccount", "description": "The loyalty account to create.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `CreateLoyaltyAccount` request. \nKeys can be any valid string, but must be unique for every request.", "readOnly": false, "required": true } ] }, { "name": "LoyaltyAccount", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the loyalty account.", "readOnly": true, "required": false }, { "name": "program_id", "type": "string", "description": "The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram) to which the account belongs.", "readOnly": false, "required": true }, { "name": "balance", "type": "integer", "description": "The available point balance in the loyalty account. If points are scheduled to expire, they are listed in the `expiring_point_deadlines` field.\n\nYour application should be able to handle loyalty accounts that have a negative point balance (`balance` is less than 0). This might occur if a seller makes a manual adjustment or as a result of a refund or exchange.", "readOnly": true, "required": false }, { "name": "lifetime_points", "type": "integer", "description": "The total points accrued during the lifetime of the account.", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "The Square-assigned ID of the [customer](entity:Customer) that is associated with the account.", "readOnly": false, "required": false }, { "name": "enrolled_at", "type": "string", "description": "The timestamp when the buyer joined the loyalty program, in RFC 3339 format. This field is used to display the **Enrolled On** or **Member Since** date in first-party Square products.\n\nIf this field is not set in a `CreateLoyaltyAccount` request, Square populates it after the buyer's first action on their account \n(when `AccumulateLoyaltyPoints` or `CreateLoyaltyReward` is called). In first-party flows, Square populates the field when the buyer agrees to the terms of service in Square Point of Sale. \n\nThis field is typically specified in a `CreateLoyaltyAccount` request when creating a loyalty account for a buyer who already interacted with their account. \nFor example, you would set this field when migrating accounts from an external system. The timestamp in the request can represent a current or previous date and time, but it cannot be set for the future.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the loyalty account was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the loyalty account was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "mapping", "type": "#/components/schemas/LoyaltyAccountMapping", "description": "The mapping that associates the loyalty account with a buyer. Currently,\na loyalty account can only be mapped to a buyer by phone number.\n\nTo create a loyalty account, you must specify the `mapping` field, with the buyer's phone number\nin the `phone_number` field.", "readOnly": false, "required": false }, { "name": "expiring_point_deadlines", "type": "array", "description": "The schedule for when points expire in the loyalty account balance. This field is present only if the account has points that are scheduled to expire. \n\nThe total number of points in this field equals the number of points in the `balance` field.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/LoyaltyAccountExpiringPointDeadline" } ] }, { "name": "LoyaltyAccountMapping", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the mapping.", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the mapping was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number of the buyer, in E.164 format. For example, \"+14155551111\".", "readOnly": false, "required": false } ] }, { "name": "LoyaltyAccountExpiringPointDeadline", "properties": [ { "name": "points", "type": "integer", "description": "The number of points scheduled to expire at the `expires_at` timestamp.", "readOnly": false, "required": true }, { "name": "expires_at", "type": "string", "description": "The timestamp of when the points are scheduled to expire, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": true } ] } ], "SearchLoyaltyAccountsRequest": [ { "name": "SearchLoyaltyAccountsRequest", "properties": [ { "name": "query", "type": "#/components/schemas/SearchLoyaltyAccountsRequestLoyaltyAccountQuery", "description": "The search criteria for the request.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to include in the response. The default value is 30.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to \nthis endpoint. Provide this to retrieve the next set of \nresults for the original query.\n\nFor more information, \nsee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] }, { "name": "SearchLoyaltyAccountsRequestLoyaltyAccountQuery", "properties": [ { "name": "mappings", "type": "array", "description": "The set of mappings to use in the loyalty account search. \n\nThis cannot be combined with `customer_ids`. \n\nMax: 30 mappings", "readOnly": false, "required": false, "arrayType": "#/components/schemas/LoyaltyAccountMapping" }, { "name": "customer_ids", "type": "array", "description": "The set of customer IDs to use in the loyalty account search. \n\nThis cannot be combined with `mappings`. \n\nMax: 30 customer IDs", "readOnly": false, "required": false } ] }, { "name": "LoyaltyAccountMapping", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the mapping.", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the mapping was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number of the buyer, in E.164 format. For example, \"+14155551111\".", "readOnly": false, "required": false } ] } ], "RetrieveLoyaltyAccountRequest": [ { "name": "RetrieveLoyaltyAccountRequest", "properties": [ { "name": "account_id", "type": "string", "description": "The ID of the [loyalty account](entity:LoyaltyAccount) to retrieve.", "readOnly": false, "required": true } ] } ], "AccumulateLoyaltyPointsRequest": [ { "name": "AccumulateLoyaltyPointsRequest", "properties": [ { "name": "accumulate_points", "type": "#/components/schemas/LoyaltyEventAccumulatePoints", "description": "The points to add to the account. \nIf you are using the Orders API to manage orders, specify the order ID.\nOtherwise, specify the points to add.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies the `AccumulateLoyaltyPoints` request. \nKeys can be any valid string but must be unique for every request.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The [location](entity:Location) where the purchase was made.", "readOnly": false, "required": true }, { "name": "account_id", "type": "string", "description": "The ID of the target [loyalty account](entity:LoyaltyAccount).", "readOnly": false, "required": true } ] }, { "name": "LoyaltyEventAccumulatePoints", "properties": [ { "name": "loyalty_program_id", "type": "string", "description": "The ID of the [loyalty program](entity:LoyaltyProgram).", "readOnly": true, "required": false }, { "name": "points", "type": "integer", "description": "The number of points accumulated by the event.", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the [order](entity:Order) for which the buyer accumulated the points.\nThis field is returned only if the Orders API is used to process orders.", "readOnly": false, "required": false } ] } ], "AdjustLoyaltyPointsRequest": [ { "name": "AdjustLoyaltyPointsRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `AdjustLoyaltyPoints` request. \nKeys can be any valid string, but must be unique for every request.", "readOnly": false, "required": true }, { "name": "adjust_points", "type": "#/components/schemas/LoyaltyEventAdjustPoints", "description": "The points to add or subtract and the reason for the adjustment. To add points, specify a positive integer.\nTo subtract points, specify a negative integer.", "readOnly": false, "required": true }, { "name": "allow_negative_balance", "type": "boolean", "description": "Indicates whether to allow a negative adjustment to result in a negative balance. If `true`, a negative\nbalance is allowed when subtracting points. If `false`, Square returns a `BAD_REQUEST` error when subtracting\nthe specified number of points would result in a negative balance. The default value is `false`.", "readOnly": false, "required": false }, { "name": "account_id", "type": "string", "description": "The ID of the target [loyalty account](entity:LoyaltyAccount).", "readOnly": false, "required": true } ] }, { "name": "LoyaltyEventAdjustPoints", "properties": [ { "name": "loyalty_program_id", "type": "string", "description": "The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram).", "readOnly": true, "required": false }, { "name": "points", "type": "integer", "description": "The number of points added or removed.", "readOnly": false, "required": true }, { "name": "reason", "type": "string", "description": "The reason for the adjustment of points.", "readOnly": false, "required": false } ] } ], "SearchLoyaltyEventsRequest": [ { "name": "SearchLoyaltyEventsRequest", "properties": [ { "name": "query", "type": "#/components/schemas/LoyaltyEventQuery", "description": "A set of one or more predefined query filters to apply when \nsearching for loyalty events. The endpoint performs a logical AND to \nevaluate multiple filters and performs a logical OR on arrays \nthat specifies multiple field values.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to include in the response. \nThe last page might contain fewer events. \nThe default is 30 events.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for your original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] }, { "name": "LoyaltyEventQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/LoyaltyEventFilter", "description": "The query filter criteria.", "readOnly": false, "required": false } ] }, { "name": "LoyaltyEventFilter", "properties": [ { "name": "loyalty_account_filter", "type": "#/components/schemas/LoyaltyEventLoyaltyAccountFilter", "description": "Filter events by loyalty account.", "readOnly": false, "required": false }, { "name": "type_filter", "type": "#/components/schemas/LoyaltyEventTypeFilter", "description": "Filter events by event type.", "readOnly": false, "required": false }, { "name": "date_time_filter", "type": "#/components/schemas/LoyaltyEventDateTimeFilter", "description": "Filter events by date time range. \nFor each range, the start time is inclusive and the end time \nis exclusive.", "readOnly": false, "required": false }, { "name": "location_filter", "type": "#/components/schemas/LoyaltyEventLocationFilter", "description": "Filter events by location.", "readOnly": false, "required": false }, { "name": "order_filter", "type": "#/components/schemas/LoyaltyEventOrderFilter", "description": "Filter events by the order associated with the event.", "readOnly": false, "required": false } ] }, { "name": "LoyaltyEventLoyaltyAccountFilter", "properties": [ { "name": "loyalty_account_id", "type": "string", "description": "The ID of the [loyalty account](entity:LoyaltyAccount) associated with loyalty events.", "readOnly": false, "required": true } ] }, { "name": "LoyaltyEventTypeFilter", "properties": [ { "name": "types", "type": "array", "description": "The loyalty event types used to filter the result.\nIf multiple values are specified, the endpoint uses a \nlogical OR to combine them.\n", "readOnly": false, "required": true, "arrayType": "#/components/schemas/LoyaltyEventType" } ] }, { "name": "LoyaltyEventType", "properties": [] }, { "name": "LoyaltyEventDateTimeFilter", "properties": [ { "name": "created_at", "type": "#/components/schemas/TimeRange", "description": "The `created_at` date time range used to filter the result.", "readOnly": false, "required": true } ] }, { "name": "TimeRange", "properties": [ { "name": "start_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nstarts.", "readOnly": false, "required": false }, { "name": "end_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nends.", "readOnly": false, "required": false } ] }, { "name": "LoyaltyEventLocationFilter", "properties": [ { "name": "location_ids", "type": "array", "description": "The [location](entity:Location) IDs for loyalty events to query.\nIf multiple values are specified, the endpoint uses \na logical OR to combine them.", "readOnly": false, "required": true } ] }, { "name": "LoyaltyEventOrderFilter", "properties": [ { "name": "order_id", "type": "string", "description": "The ID of the [order](entity:Order) associated with the event.", "readOnly": false, "required": true } ] } ], "RetrieveLoyaltyProgramRequest": [ { "name": "RetrieveLoyaltyProgramRequest", "properties": [ { "name": "program_id", "type": "string", "description": "The ID of the loyalty program or the keyword `main`. Either value can be used to retrieve the single loyalty program that belongs to the seller.", "readOnly": false, "required": true } ] } ], "CalculateLoyaltyPointsRequest": [ { "name": "CalculateLoyaltyPointsRequest", "properties": [ { "name": "order_id", "type": "string", "description": "The [order](entity:Order) ID for which to calculate the points.\nSpecify this field if your application uses the Orders API to process orders.\nOtherwise, specify the `transaction_amount_money`.", "readOnly": false, "required": false }, { "name": "transaction_amount_money", "type": "#/components/schemas/Money", "description": "The purchase amount for which to calculate the points. \nSpecify this field if your application does not use the Orders API to process orders.\nOtherwise, specify the `order_id`.", "readOnly": false, "required": false }, { "name": "loyalty_account_id", "type": "string", "description": "The ID of the target [loyalty account](entity:LoyaltyAccount). Optionally specify this field\nif your application uses the Orders API to process orders.\n\nIf specified, the `promotion_points` field in the response shows the number of points the buyer would\nearn from the purchase. In this case, Square uses the account ID to determine whether the promotion's\n`trigger_limit` (the maximum number of times that a buyer can trigger the promotion) has been reached.\nIf not specified, the `promotion_points` field shows the number of points the purchase qualifies\nfor regardless of the trigger limit.", "readOnly": false, "required": false }, { "name": "program_id", "type": "string", "description": "The ID of the [loyalty program](entity:LoyaltyProgram), which defines the rules for accruing points.", "readOnly": false, "required": true } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] } ], "ListLoyaltyPromotionsRequest": [ { "name": "ListLoyaltyPromotionsRequest", "properties": [ { "name": "status", "type": "#/components/schemas/LoyaltyPromotionStatus", "description": "The status to filter the results by. If a status is provided, only loyalty promotions\nwith the specified status are returned. Otherwise, all loyalty promotions associated with\nthe loyalty program are returned.\n", "readOnly": true, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response.\nThe minimum value is 1 and the maximum value is 30. The default value is 30.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "program_id", "type": "string", "description": "The ID of the base [loyalty program](entity:LoyaltyProgram). To get the program ID,\ncall [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) using the `main` keyword.", "readOnly": false, "required": true } ] }, { "name": "LoyaltyPromotionStatus", "properties": [] } ], "CreateLoyaltyPromotionRequest": [ { "name": "CreateLoyaltyPromotionRequest", "properties": [ { "name": "loyalty_promotion", "type": "#/components/schemas/LoyaltyPromotion", "description": "The loyalty promotion to create.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, which is used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": true }, { "name": "program_id", "type": "string", "description": "The ID of the [loyalty program](entity:LoyaltyProgram) to associate with the promotion.\nTo get the program ID, call [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram)\nusing the `main` keyword.", "readOnly": false, "required": true } ] }, { "name": "LoyaltyPromotion", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the promotion.", "readOnly": true, "required": false }, { "name": "name", "type": "string", "description": "The name of the promotion.", "readOnly": false, "required": true }, { "name": "incentive", "type": "#/components/schemas/LoyaltyPromotionIncentive", "description": "The points incentive for the promotion. This field defines whether promotion points\nare earned by multiplying base program points or by adding a specified number of points.", "readOnly": false, "required": true }, { "name": "available_time", "type": "#/components/schemas/LoyaltyPromotionAvailableTimeData", "description": "The scheduling information that defines when purchases can qualify to earn points from an `ACTIVE` promotion.", "readOnly": false, "required": true }, { "name": "trigger_limit", "type": "#/components/schemas/LoyaltyPromotionTriggerLimit", "description": "The number of times a buyer can earn promotion points during a specified interval.\nIf not specified, buyers can trigger the promotion an unlimited number of times.", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/LoyaltyPromotionStatus", "description": "The current status of the promotion.\n", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp of when the promotion was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The timestamp of when the promotion was canceled, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the promotion was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "loyalty_program_id", "type": "string", "description": "The ID of the [loyalty program](entity:LoyaltyProgram) associated with the promotion.", "readOnly": true, "required": false }, { "name": "minimum_spend_amount_money", "type": "#/components/schemas/Money", "description": "The minimum purchase amount required to earn promotion points. If specified, this amount is positive.", "readOnly": false, "required": false }, { "name": "qualifying_item_variation_ids", "type": "array", "description": "The IDs of any qualifying `ITEM_VARIATION` [catalog objects](entity:CatalogObject). If specified,\nthe purchase must include at least one of these items to qualify for the promotion.\n\nThis option is valid only if the base loyalty program uses a `VISIT` or `SPEND` accrual rule.\nWith `SPEND` accrual rules, make sure that qualifying promotional items are not excluded.\n\nYou can specify `qualifying_item_variation_ids` or `qualifying_category_ids` for a given promotion, but not both.", "readOnly": false, "required": false }, { "name": "qualifying_category_ids", "type": "array", "description": "The IDs of any qualifying `CATEGORY` [catalog objects](entity:CatalogObject). If specified,\nthe purchase must include at least one item from one of these categories to qualify for the promotion.\n\nThis option is valid only if the base loyalty program uses a `VISIT` or `SPEND` accrual rule.\nWith `SPEND` accrual rules, make sure that qualifying promotional items are not excluded.\n\nYou can specify `qualifying_category_ids` or `qualifying_item_variation_ids` for a promotion, but not both.", "readOnly": false, "required": false } ] }, { "name": "LoyaltyPromotionIncentive", "properties": [ { "name": "type", "type": "#/components/schemas/LoyaltyPromotionIncentiveType", "description": "The type of points incentive.\n", "readOnly": false, "required": true }, { "name": "points_multiplier_data", "type": "#/components/schemas/LoyaltyPromotionIncentivePointsMultiplierData", "description": "Additional data for a `POINTS_MULTIPLIER` incentive type.", "readOnly": false, "required": false }, { "name": "points_addition_data", "type": "#/components/schemas/LoyaltyPromotionIncentivePointsAdditionData", "description": "Additional data for a `POINTS_ADDITION` incentive type.", "readOnly": false, "required": false } ] }, { "name": "LoyaltyPromotionIncentiveType", "properties": [] }, { "name": "LoyaltyPromotionIncentivePointsMultiplierData", "properties": [ { "name": "points_multiplier", "type": "integer", "description": "The multiplier used to calculate the number of points earned each time the promotion\nis triggered. For example, suppose a purchase qualifies for 5 points from the base loyalty program.\nIf the purchase also qualifies for a `POINTS_MULTIPLIER` promotion incentive with a `points_multiplier`\nof 3, the buyer earns a total of 15 points (5 program points x 3 promotion multiplier = 15 points).\n\nDEPRECATED at version 2023-08-16. Replaced by the `multiplier` field.\n\nOne of the following is required when specifying a points multiplier:\n- (Recommended) The `multiplier` field.\n- This deprecated `points_multiplier` field. If provided in the request, Square also returns `multiplier`\nwith the equivalent value.", "readOnly": false, "required": false }, { "name": "multiplier", "type": "string", "description": "The multiplier used to calculate the number of points earned each time the promotion is triggered,\nspecified as a string representation of a decimal. Square supports multipliers up to 10x, with three\npoint precision for decimal multipliers. For example, suppose a purchase qualifies for 4 points from the\nbase loyalty program. If the purchase also qualifies for a `POINTS_MULTIPLIER` promotion incentive with a\n`multiplier` of \"1.5\", the buyer earns a total of 6 points (4 program points x 1.5 promotion multiplier = 6 points).\nFractional points are dropped.\n\nOne of the following is required when specifying a points multiplier:\n- (Recommended) This `multiplier` field.\n- The deprecated `points_multiplier` field. If provided in the request, Square also returns `multiplier`\nwith the equivalent value.", "readOnly": false, "required": false } ] }, { "name": "LoyaltyPromotionIncentivePointsAdditionData", "properties": [ { "name": "points_addition", "type": "integer", "description": "The number of additional points to earn each time the promotion is triggered. For example,\nsuppose a purchase qualifies for 5 points from the base loyalty program. If the purchase also\nqualifies for a `POINTS_ADDITION` promotion incentive with a `points_addition` of 3, the buyer\nearns a total of 8 points (5 program points + 3 promotion points = 8 points).", "readOnly": false, "required": true } ] }, { "name": "LoyaltyPromotionAvailableTimeData", "properties": [ { "name": "start_date", "type": "string", "description": "The date that the promotion starts, in `YYYY-MM-DD` format. Square populates this field\nbased on the provided `time_periods`.", "readOnly": true, "required": false }, { "name": "end_date", "type": "string", "description": "The date that the promotion ends, in `YYYY-MM-DD` format. Square populates this field\nbased on the provided `time_periods`. If an end date is not specified, an `ACTIVE` promotion\nremains available until it is canceled.", "readOnly": true, "required": false }, { "name": "time_periods", "type": "array", "description": "A list of [iCalendar (RFC 5545) events](https://tools.ietf.org/html/rfc5545#section-3.6.1)\n(`VEVENT`). Each event represents an available time period per day or days of the week. \nA day can have a maximum of one available time period.\n\nOnly `DTSTART`, `DURATION`, and `RRULE` are supported. `DTSTART` and `DURATION` are required and\ntimestamps must be in local (unzoned) time format. Include `RRULE` to specify recurring promotions,\nan end date (using the `UNTIL` keyword), or both. For more information, see\n[Available time](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#available-time).\n\nNote that `BEGIN:VEVENT` and `END:VEVENT` are optional in a `CreateLoyaltyPromotion` request\nbut are always included in the response.", "readOnly": false, "required": true } ] }, { "name": "LoyaltyPromotionTriggerLimit", "properties": [ { "name": "times", "type": "integer", "description": "The maximum number of times a buyer can trigger the promotion during the specified `interval`.", "readOnly": false, "required": true }, { "name": "interval", "type": "#/components/schemas/LoyaltyPromotionTriggerLimitInterval", "description": "The time period the limit applies to.\n", "readOnly": false, "required": false } ] }, { "name": "LoyaltyPromotionTriggerLimitInterval", "properties": [] }, { "name": "LoyaltyPromotionStatus", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] } ], "RetrieveLoyaltyPromotionRequest": [ { "name": "RetrieveLoyaltyPromotionRequest", "properties": [ { "name": "promotion_id", "type": "string", "description": "The ID of the [loyalty promotion](entity:LoyaltyPromotion) to retrieve.", "readOnly": false, "required": true }, { "name": "program_id", "type": "string", "description": "The ID of the base [loyalty program](entity:LoyaltyProgram). To get the program ID,\ncall [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) using the `main` keyword.", "readOnly": false, "required": true } ] } ], "CancelLoyaltyPromotionRequest": [ { "name": "CancelLoyaltyPromotionRequest", "properties": [ { "name": "promotion_id", "type": "string", "description": "The ID of the [loyalty promotion](entity:LoyaltyPromotion) to cancel. You can cancel a\npromotion that has an `ACTIVE` or `SCHEDULED` status.", "readOnly": false, "required": true }, { "name": "program_id", "type": "string", "description": "The ID of the base [loyalty program](entity:LoyaltyProgram).", "readOnly": false, "required": true } ] } ], "CreateLoyaltyRewardRequest": [ { "name": "CreateLoyaltyRewardRequest", "properties": [ { "name": "reward", "type": "#/components/schemas/LoyaltyReward", "description": "The reward to create.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `CreateLoyaltyReward` request. \nKeys can be any valid string, but must be unique for every request.", "readOnly": false, "required": true } ] }, { "name": "LoyaltyReward", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the loyalty reward.", "readOnly": true, "required": false }, { "name": "status", "type": "#/components/schemas/LoyaltyRewardStatus", "description": "The status of a loyalty reward.\n", "readOnly": true, "required": false }, { "name": "loyalty_account_id", "type": "string", "description": "The Square-assigned ID of the [loyalty account](entity:LoyaltyAccount) to which the reward belongs.", "readOnly": false, "required": true }, { "name": "reward_tier_id", "type": "string", "description": "The Square-assigned ID of the [reward tier](entity:LoyaltyProgramRewardTier) used to create the reward.", "readOnly": false, "required": true }, { "name": "points", "type": "integer", "description": "The number of loyalty points used for the reward.", "readOnly": true, "required": false }, { "name": "order_id", "type": "string", "description": "The Square-assigned ID of the [order](entity:Order) to which the reward is attached.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the reward was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the reward was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "redeemed_at", "type": "string", "description": "The timestamp when the reward was redeemed, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "LoyaltyRewardStatus", "properties": [] } ], "SearchLoyaltyRewardsRequest": [ { "name": "SearchLoyaltyRewardsRequest", "properties": [ { "name": "query", "type": "#/components/schemas/SearchLoyaltyRewardsRequestLoyaltyRewardQuery", "description": "The search criteria for the request. \nIf empty, the endpoint retrieves all loyalty rewards in the loyalty program.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in the response. The default value is 30.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to \nthis endpoint. Provide this to retrieve the next set of \nresults for the original query.\nFor more information, \nsee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] }, { "name": "SearchLoyaltyRewardsRequestLoyaltyRewardQuery", "properties": [ { "name": "loyalty_account_id", "type": "string", "description": "The ID of the [loyalty account](entity:LoyaltyAccount) to which the loyalty reward belongs.", "readOnly": false, "required": true }, { "name": "status", "type": "#/components/schemas/LoyaltyRewardStatus", "description": "The status of the loyalty reward.\n", "readOnly": false, "required": false } ] }, { "name": "LoyaltyRewardStatus", "properties": [] } ], "DeleteLoyaltyRewardRequest": [ { "name": "DeleteLoyaltyRewardRequest", "properties": [ { "name": "reward_id", "type": "string", "description": "The ID of the [loyalty reward](entity:LoyaltyReward) to delete.", "readOnly": false, "required": true } ] } ], "RetrieveLoyaltyRewardRequest": [ { "name": "RetrieveLoyaltyRewardRequest", "properties": [ { "name": "reward_id", "type": "string", "description": "The ID of the [loyalty reward](entity:LoyaltyReward) to retrieve.", "readOnly": false, "required": true } ] } ], "RedeemLoyaltyRewardRequest": [ { "name": "RedeemLoyaltyRewardRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `RedeemLoyaltyReward` request. \nKeys can be any valid string, but must be unique for every request.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The ID of the [location](entity:Location) where the reward is redeemed.", "readOnly": false, "required": true }, { "name": "reward_id", "type": "string", "description": "The ID of the [loyalty reward](entity:LoyaltyReward) to redeem.", "readOnly": false, "required": true } ] } ], "ListMerchantCustomAttributeDefinitionsRequest": [ { "name": "ListMerchantCustomAttributeDefinitionsRequest", "properties": [ { "name": "visibility_filter", "type": "#/components/schemas/VisibilityFilter", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.\n", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] }, { "name": "VisibilityFilter", "properties": [] } ], "CreateMerchantCustomAttributeDefinitionRequest": [ { "name": "CreateMerchantCustomAttributeDefinitionRequest", "properties": [ { "name": "custom_attribute_definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "The custom attribute definition to create. Note the following:\n- With the exception of the `Selection` data type, the `schema` is specified as a simple URL to the JSON schema\ndefinition hosted on the Square CDN. For more information, including supported values and constraints, see\n[Supported data types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types).\n- `name` is required unless `visibility` is set to `VISIBILITY_HIDDEN`.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false } ] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] } ], "DeleteMerchantCustomAttributeDefinitionRequest": [ { "name": "DeleteMerchantCustomAttributeDefinitionRequest", "properties": [ { "name": "key", "type": "string", "description": "The key of the custom attribute definition to delete.", "readOnly": false, "required": true } ] } ], "RetrieveMerchantCustomAttributeDefinitionRequest": [ { "name": "RetrieveMerchantCustomAttributeDefinitionRequest", "properties": [ { "name": "version", "type": "integer", "description": "The current version of the custom attribute definition, which is used for strongly consistent\nreads to guarantee that you receive the most up-to-date data. When included in the request,\nSquare returns the specified version or a higher version if one exists. If the specified version\nis higher than the current version, Square returns a `BAD_REQUEST` error.", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "The key of the custom attribute definition to retrieve. If the requesting application\nis not the definition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "UpdateMerchantCustomAttributeDefinitionRequest": [ { "name": "UpdateMerchantCustomAttributeDefinitionRequest", "properties": [ { "name": "custom_attribute_definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "The custom attribute definition that contains the fields to update. This endpoint\nsupports sparse updates, so only new or changed fields need to be included in the request.\nOnly the following fields can be updated:\n- `name`\n- `description`\n- `visibility`\n- `schema` for a `Selection` data type. Only changes to the named options or the maximum number of allowed\nselections are supported.\nFor more information, see\n[Update a merchant custom attribute definition](https://developer.squareup.com/docs/merchant-custom-attributes-api/custom-attribute-definitions#update-custom-attribute-definition).\nThe version field must match the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\nIf this is not important for your application, version can be set to -1. For any other values, the request fails with a BAD_REQUEST error.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "The key of the custom attribute definition to update.", "readOnly": false, "required": true } ] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] } ], "BulkDeleteMerchantCustomAttributesRequest": [ { "name": "BulkDeleteMerchantCustomAttributesRequest", "properties": [ { "name": "values", "type": "map", "description": "The data used to update the `CustomAttribute` objects.\nThe keys must be unique and are used to map to the corresponding response.", "readOnly": false, "required": true } ] } ], "BulkUpsertMerchantCustomAttributesRequest": [ { "name": "BulkUpsertMerchantCustomAttributesRequest", "properties": [ { "name": "values", "type": "map", "description": "A map containing 1 to 25 individual upsert requests. For each request, provide an\narbitrary ID that is unique for this `BulkUpsertMerchantCustomAttributes` request and the\ninformation needed to create or update a custom attribute.", "readOnly": false, "required": true } ] } ], "ListMerchantCustomAttributesRequest": [ { "name": "ListMerchantCustomAttributesRequest", "properties": [ { "name": "visibility_filter", "type": "#/components/schemas/VisibilityFilter", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.\n", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request. For more\ninformation, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "with_definitions", "type": "boolean", "description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each\ncustom attribute. Set this parameter to `true` to get the name and description of each custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the target [merchant](entity:Merchant).", "readOnly": false, "required": true } ] }, { "name": "VisibilityFilter", "properties": [] } ], "DeleteMerchantCustomAttributeRequest": [ { "name": "DeleteMerchantCustomAttributeRequest", "properties": [ { "name": "merchant_id", "type": "string", "description": "The ID of the target [merchant](entity:Merchant).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to delete. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "RetrieveMerchantCustomAttributeRequest": [ { "name": "RetrieveMerchantCustomAttributeRequest", "properties": [ { "name": "with_definition", "type": "boolean", "description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of\nthe custom attribute. Set this parameter to `true` to get the name and description of the custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The current version of the custom attribute, which is used for strongly consistent reads to\nguarantee that you receive the most up-to-date data. When included in the request, Square\nreturns the specified version or a higher version if one exists. If the specified version is\nhigher than the current version, Square returns a `BAD_REQUEST` error.", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the target [merchant](entity:Merchant).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to retrieve. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "readOnly": false, "required": true } ] } ], "UpsertMerchantCustomAttributeRequest": [ { "name": "UpsertMerchantCustomAttributeRequest", "properties": [ { "name": "custom_attribute", "type": "#/components/schemas/CustomAttribute", "description": "The custom attribute to create or update, with the following fields:\n- `value`. This value must conform to the `schema` specified by the definition.\nFor more information, see [Supported data types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types).\n- The version field must match the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\nIf this is not important for your application, version can be set to -1. For any other values, the request fails with a BAD_REQUEST error.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. For more information,\nsee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the target [merchant](entity:Merchant).", "readOnly": false, "required": true }, { "name": "key", "type": "string", "description": "The key of the custom attribute to create or update. This key must match the `key` of a\ncustom attribute definition in the Square seller account. If the requesting application is not\nthe definition owner, you must use the qualified key.", "readOnly": false, "required": true } ] }, { "name": "CustomAttribute", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).", "readOnly": false, "required": false }, { "name": "value", "type": "string", "description": "The value assigned to the custom attribute. It is validated against the custom\nattribute definition's schema on write operations. For more information about custom\nattribute values,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute. This field is incremented when the custom attribute is changed.\nWhen updating an existing custom attribute value, you can provide this field\nand specify the current version of the custom attribute to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "A copy of the `visibility` field value for the associated custom attribute definition.\n", "readOnly": true, "required": false }, { "name": "definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "A copy of the associated custom attribute definition object. This field is only set when\nthe optional field is specified on the request.", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute was created or was most recently\nupdated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "ListMerchantsRequest": [ { "name": "ListMerchantsRequest", "properties": [ { "name": "cursor", "type": "integer", "description": "The cursor generated by the previous response.", "readOnly": false, "required": false } ] } ], "RetrieveMerchantRequest": [ { "name": "RetrieveMerchantRequest", "properties": [ { "name": "merchant_id", "type": "string", "description": "The ID of the merchant to retrieve. If the string \"me\" is supplied as the ID,\nthen retrieve the merchant that is currently accessible to this call.", "readOnly": false, "required": true } ] } ], "RevokeTokenRequest": [ { "name": "RevokeTokenRequest", "properties": [ { "name": "client_id", "type": "string", "description": "The Square-issued ID for your application, which is available on the **OAuth** page in the\n[Developer Dashboard](https://developer.squareup.com/apps).", "readOnly": false, "required": false }, { "name": "access_token", "type": "string", "description": "The access token of the merchant whose token you want to revoke.\nDo not provide a value for `merchant_id` if you provide this parameter.", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the merchant whose token you want to revoke.\nDo not provide a value for `access_token` if you provide this parameter.", "readOnly": false, "required": false }, { "name": "revoke_only_access_token", "type": "boolean", "description": "If `true`, terminate the given single access token, but do not\nterminate the entire authorization.\nDefault: `false`", "readOnly": false, "required": false } ] } ], "ObtainTokenRequest": [ { "name": "ObtainTokenRequest", "properties": [ { "name": "client_id", "type": "string", "description": "The Square-issued ID of your application, which is available on the **OAuth** page in the\n[Developer Dashboard](https://developer.squareup.com/apps).", "readOnly": false, "required": true }, { "name": "client_secret", "type": "string", "description": "The Square-issued application secret for your application, which is available on the **OAuth** page\nin the [Developer Dashboard](https://developer.squareup.com/apps). This parameter is only required when \nyou're not using the [OAuth PKCE (Proof Key for Code Exchange) flow](https://developer.squareup.com/docs/oauth-api/overview#pkce-flow).\nThe PKCE flow requires a `code_verifier` instead of a `client_secret` when `grant_type` is set to `authorization_code`. \nIf `grant_type` is set to `refresh_token` and the `refresh_token` is obtained uaing PKCE, the PKCE flow only requires `client_id`, \n`grant_type`, and `refresh_token`.", "readOnly": false, "required": false }, { "name": "code", "type": "string", "description": "The authorization code to exchange.\nThis code is required if `grant_type` is set to `authorization_code` to indicate that\nthe application wants to exchange an authorization code for an OAuth access token.", "readOnly": false, "required": false }, { "name": "redirect_uri", "type": "string", "description": "The redirect URL assigned on the **OAuth** page for your application in the [Developer Dashboard](https://developer.squareup.com/apps).", "readOnly": false, "required": false }, { "name": "grant_type", "type": "string", "description": "Specifies the method to request an OAuth access token.\nValid values are `authorization_code`, `refresh_token`, and `migration_token`.", "readOnly": false, "required": true }, { "name": "refresh_token", "type": "string", "description": "A valid refresh token for generating a new OAuth access token.\n\nA valid refresh token is required if `grant_type` is set to `refresh_token`\nto indicate that the application wants a replacement for an expired OAuth access token.", "readOnly": false, "required": false }, { "name": "migration_token", "type": "string", "description": "A legacy OAuth access token obtained using a Connect API version prior\nto 2019-03-13. This parameter is required if `grant_type` is set to\n`migration_token` to indicate that the application wants to get a replacement\nOAuth access token. The response also returns a refresh token.\nFor more information, see [Migrate to Using Refresh Tokens](https://developer.squareup.com/docs/oauth-api/migrate-to-refresh-tokens).", "readOnly": false, "required": false }, { "name": "scopes", "type": "array", "description": "A JSON list of strings representing the permissions that the application is requesting.\nFor example, \"`[\"MERCHANT_PROFILE_READ\",\"PAYMENTS_READ\",\"BANK_ACCOUNTS_READ\"]`\".\n\nThe access token returned in the response is granted the permissions\nthat comprise the intersection between the requested list of permissions and those\nthat belong to the provided refresh token.", "readOnly": false, "required": false }, { "name": "short_lived", "type": "boolean", "description": "A Boolean indicating a request for a short-lived access token.\n\nThe short-lived access token returned in the response expires in 24 hours.", "readOnly": false, "required": false }, { "name": "code_verifier", "type": "string", "description": "Must be provided when using the PKCE OAuth flow if `grant_type` is set to `authorization_code`. The `code_verifier` is used to verify against the\n`code_challenge` associated with the `authorization_code`.", "readOnly": false, "required": false } ] } ], "RetrieveTokenStatusRequest": [ { "name": "RetrieveTokenStatusRequest", "properties": [] } ], "ListOrderCustomAttributeDefinitionsRequest": [ { "name": "ListOrderCustomAttributeDefinitionsRequest", "properties": [ { "name": "visibility_filter", "type": "#/components/schemas/VisibilityFilter", "description": "Requests that all of the custom attributes be returned, or only those that are read-only or read-write.\n", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint. \nProvide this cursor to retrieve the next page of results for your original request. \nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory. \nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. \nThe default value is 20.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "readOnly": false, "required": false } ] }, { "name": "VisibilityFilter", "properties": [] } ], "CreateOrderCustomAttributeDefinitionRequest": [ { "name": "CreateOrderCustomAttributeDefinitionRequest", "properties": [ { "name": "custom_attribute_definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "The custom attribute definition to create. Note the following:\n- With the exception of the `Selection` data type, the `schema` is specified as a simple URL to the JSON schema\ndefinition hosted on the Square CDN. For more information, including supported values and constraints, see\n[Specifying the schema](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attribute-definitions#specify-schema).\n- If provided, `name` must be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller.\n- All custom attributes are visible in exported customer data, including those set to `VISIBILITY_HIDDEN`.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. \nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false } ] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] } ], "DeleteOrderCustomAttributeDefinitionRequest": [ { "name": "DeleteOrderCustomAttributeDefinitionRequest", "properties": [ { "name": "key", "type": "string", "description": "The key of the custom attribute definition to delete.", "readOnly": false, "required": true } ] } ], "RetrieveOrderCustomAttributeDefinitionRequest": [ { "name": "RetrieveOrderCustomAttributeDefinitionRequest", "properties": [ { "name": "version", "type": "integer", "description": "To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol, include this optional field and specify the current version of the custom attribute.", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "The key of the custom attribute definition to retrieve.", "readOnly": false, "required": true } ] } ], "UpdateOrderCustomAttributeDefinitionRequest": [ { "name": "UpdateOrderCustomAttributeDefinitionRequest", "properties": [ { "name": "custom_attribute_definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "The custom attribute definition that contains the fields to update. This endpoint supports sparse updates, \nso only new or changed fields need to be included in the request. For more information, see \n[Updatable definition fields](https://developer.squareup.com/docs/orders-custom-attributes-api/custom-attribute-definitions#updatable-definition-fields).\n\nTo enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control, include the optional `version` field and specify the current version of the custom attribute definition.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. \nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "key", "type": "string", "description": "The key of the custom attribute definition to update.", "readOnly": false, "required": true } ] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] } ], "BulkDeleteOrderCustomAttributesRequest": [ { "name": "BulkDeleteOrderCustomAttributesRequest", "properties": [ { "name": "values", "type": "map", "description": "A map of requests that correspond to individual delete operations for custom attributes.", "readOnly": false, "required": true } ] } ], "BulkUpsertOrderCustomAttributesRequest": [ { "name": "BulkUpsertOrderCustomAttributesRequest", "properties": [ { "name": "values", "type": "map", "description": "A map of requests that correspond to individual upsert operations for custom attributes.", "readOnly": false, "required": true } ] } ], "ListOrderCustomAttributesRequest": [ { "name": "ListOrderCustomAttributesRequest", "properties": [ { "name": "visibility_filter", "type": "#/components/schemas/VisibilityFilter", "description": "Requests that all of the custom attributes be returned, or only those that are read-only or read-write.\n", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint. \nProvide this cursor to retrieve the next page of results for your original request. \nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory. \nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. \nThe default value is 20.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "readOnly": false, "required": false }, { "name": "with_definitions", "type": "boolean", "description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each\ncustom attribute. Set this parameter to `true` to get the name and description of each custom attribute, \ninformation about the data type, or other definition details. The default value is `false`.", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the target [order](entity:Order).", "readOnly": false, "required": true } ] }, { "name": "VisibilityFilter", "properties": [] } ], "DeleteOrderCustomAttributeRequest": [ { "name": "DeleteOrderCustomAttributeRequest", "properties": [ { "name": "order_id", "type": "string", "description": "The ID of the target [order](entity:Order).", "readOnly": false, "required": true }, { "name": "custom_attribute_key", "type": "string", "description": "The key of the custom attribute to delete. This key must match the key of an\nexisting custom attribute definition.", "readOnly": false, "required": true } ] } ], "RetrieveOrderCustomAttributeRequest": [ { "name": "RetrieveOrderCustomAttributeRequest", "properties": [ { "name": "version", "type": "integer", "description": "To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol, include this optional field and specify the current version of the custom attribute.", "readOnly": false, "required": false }, { "name": "with_definition", "type": "boolean", "description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each \ncustom attribute. Set this parameter to `true` to get the name and description of each custom attribute, \ninformation about the data type, or other definition details. The default value is `false`.", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the target [order](entity:Order).", "readOnly": false, "required": true }, { "name": "custom_attribute_key", "type": "string", "description": "The key of the custom attribute to retrieve. This key must match the key of an\nexisting custom attribute definition.", "readOnly": false, "required": true } ] } ], "UpsertOrderCustomAttributeRequest": [ { "name": "UpsertOrderCustomAttributeRequest", "properties": [ { "name": "custom_attribute", "type": "#/components/schemas/CustomAttribute", "description": "The custom attribute to create or update, with the following fields:\n\n- `value`. This value must conform to the `schema` specified by the definition. \nFor more information, see [Value data types](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attributes#value-data-types).\n\n- `version`. To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol, include this optional field and specify the current version of the custom attribute.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. \nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the target [order](entity:Order).", "readOnly": false, "required": true }, { "name": "custom_attribute_key", "type": "string", "description": "The key of the custom attribute to create or update. This key must match the key \nof an existing custom attribute definition.", "readOnly": false, "required": true } ] }, { "name": "CustomAttribute", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).", "readOnly": false, "required": false }, { "name": "value", "type": "string", "description": "The value assigned to the custom attribute. It is validated against the custom\nattribute definition's schema on write operations. For more information about custom\nattribute values,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute. This field is incremented when the custom attribute is changed.\nWhen updating an existing custom attribute value, you can provide this field\nand specify the current version of the custom attribute to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "A copy of the `visibility` field value for the associated custom attribute definition.\n", "readOnly": true, "required": false }, { "name": "definition", "type": "#/components/schemas/CustomAttributeDefinition", "description": "A copy of the associated custom attribute definition object. This field is only set when\nthe optional field is specified on the request.", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute was created or was most recently\nupdated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "CustomAttributeDefinitionVisibility", "properties": [] }, { "name": "CustomAttributeDefinition", "properties": [ { "name": "key", "type": "string", "description": "The identifier\nof the custom attribute definition and its corresponding custom attributes. This value\ncan be a simple key, which is the key that is provided when the custom attribute definition\nis created, or a qualified key, if the requesting\napplication is not the definition owner. The qualified key consists of the application ID\nof the custom attribute definition owner\nfollowed by the simple key that was provided when the definition was created. It has the\nformat application_id:simple key.\n\nThe value for a simple key can contain up to 60 alphanumeric characters, periods (.),\nunderscores (_), and hyphens (-).\n\nThis field can not be changed\nafter the custom attribute definition is created. This field is required when creating\na definition and must be unique per application, seller, and resource type.", "readOnly": false, "required": false }, { "name": "schema", "type": "object", "description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must\nbe unique within the seller and application pair. This field is required if the\n`visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "description", "type": "string", "description": "Seller-oriented description of the custom attribute definition, including any constraints\nthat the seller should observe. May be displayed as a tooltip in Square UIs. This field is\nrequired if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "readOnly": false, "required": false }, { "name": "visibility", "type": "#/components/schemas/CustomAttributeDefinitionVisibility", "description": "Specifies how the custom attribute definition and its values should be shared with\nthe seller and other applications. If no value is specified, the value defaults to `VISIBILITY_HIDDEN`.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "Read only. The current version of the custom attribute definition.\nThe value is incremented each time the custom attribute definition is updated.\nWhen updating a custom attribute definition, you can provide this field\nand specify the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).\n\nOn writes, this field must be set to the latest version. Stale writes are rejected.\n\nThis field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads,\nsee [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).", "readOnly": false, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created or most recently updated,\nin RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "CreateOrderRequest": [ { "name": "CreateOrderRequest", "properties": [ { "name": "order", "type": "#/components/schemas/Order", "description": "The order to create. If this field is set, the only other top-level field that can be\nset is the `idempotency_key`.", "readOnly": false, "required": false }, { "name": "idempotency_key", "type": "string", "description": "A value you specify that uniquely identifies this\norder among orders you have created.\n\nIf you are unsure whether a particular order was created successfully,\nyou can try it again with the same idempotency key without\nworrying about creating duplicate orders.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false } ] }, { "name": "Order", "properties": [ { "name": "id", "type": "string", "description": "The order's unique ID.", "readOnly": true, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the seller location that this order is associated with.", "readOnly": false, "required": true }, { "name": "reference_id", "type": "string", "description": "A client-specified ID to associate an entity in another system\nwith this order.", "readOnly": false, "required": false }, { "name": "source", "type": "#/components/schemas/OrderSource", "description": "The origination details of the order.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the [customer](entity:Customer) associated with the order.\n\nYou should specify a `customer_id` on the order (or the payment) to ensure that transactions\nare reliably linked to customers. Omitting this field might result in the creation of new\n[instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles).", "readOnly": false, "required": false }, { "name": "line_items", "type": "array", "description": "The line items included in the order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItem" }, { "name": "taxes", "type": "array", "description": "The list of all taxes associated with the order.\n\nTaxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an\n`OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes\nwith `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item.\n\nOn reads, each tax in the list includes the total amount of that tax applied to the order.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated\n`line_items.taxes` field results in an error. Use `line_items.applied_taxes`\ninstead.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemTax" }, { "name": "discounts", "type": "array", "description": "The list of all discounts associated with the order.\n\nDiscounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`,\nan `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to.\nFor discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount`\nfor every line item.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated\n`line_items.discounts` field results in an error. Use `line_items.applied_discounts`\ninstead.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemDiscount" }, { "name": "service_charges", "type": "array", "description": "A list of service charges applied to the order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderServiceCharge" }, { "name": "fulfillments", "type": "array", "description": "Details about order fulfillment.\n\nOrders can only be created with at most one fulfillment. However, orders returned\nby the API might contain multiple fulfillments.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Fulfillment" }, { "name": "returns", "type": "array", "description": "A collection of items from sale orders being returned in this one. Normally part of an\nitemized return or exchange. There is exactly one `Return` object per sale `Order` being\nreferenced.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturn" }, { "name": "return_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "The rollup of the returned money amounts.", "readOnly": true, "required": false }, { "name": "net_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "The net money amounts (sale money - return money).", "readOnly": true, "required": false }, { "name": "rounding_adjustment", "type": "#/components/schemas/OrderRoundingAdjustment", "description": "A positive rounding adjustment to the total of the order. This adjustment is commonly\nused to apply cash rounding when the minimum unit of account is smaller than the lowest physical\ndenomination of the currency.", "readOnly": true, "required": false }, { "name": "tenders", "type": "array", "description": "The tenders that were used to pay for the order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/Tender" }, { "name": "refunds", "type": "array", "description": "The refunds that are part of this order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/Refund" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp for when the order was created, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "closed_at", "type": "string", "description": "The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "state", "type": "#/components/schemas/OrderState", "description": "The current state of the order.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The version number, which is incremented each time an update is committed to the order.\nOrders not created through the API do not include a version number and\ntherefore cannot be updated.\n\n[Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders).", "readOnly": false, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_tip_money", "type": "#/components/schemas/Money", "description": "The total amount of tip money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of money collected in service charges for the order.\n\nNote: `total_service_charge_money` is the sum of `applied_money` fields for each individual\nservice charge. Therefore, `total_service_charge_money` only includes inclusive tax amounts,\nnot additive tax amounts.", "readOnly": true, "required": false }, { "name": "ticket_name", "type": "string", "description": "A short-term identifier for the order (such as a customer first name,\ntable number, or auto-generated order number that resets daily).", "readOnly": false, "required": false }, { "name": "pricing_options", "type": "#/components/schemas/OrderPricingOptions", "description": "Pricing options for an order. The options affect how the order's price is calculated.\nThey can be used, for example, to apply automatic price adjustments that are based on\npreconfigured [pricing rules](entity:CatalogPricingRule).", "readOnly": false, "required": false }, { "name": "rewards", "type": "array", "description": "A set-like list of Rewards that have been added to the Order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReward" }, { "name": "net_amount_due_money", "type": "#/components/schemas/Money", "description": "The net amount of money due on the order.", "readOnly": true, "required": false } ] }, { "name": "OrderSource", "properties": [ { "name": "name", "type": "string", "description": "The name used to identify the place (physical or digital) that an order originates.\nIf unset, the name defaults to the name of the application that created the order.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItem", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the line item only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the line item.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The count, or measurement, of a line item being purchased:\n\nIf `quantity` is a whole number, and `quantity_unit` is not specified, then `quantity` denotes an item count. For example: `3` apples.\n\nIf `quantity` is a whole or decimal number, and `quantity_unit` is also specified, then `quantity` denotes a measurement. For example: `2.25` pounds of broccoli.\n\nFor more information, see [Specify item quantity and measurement unit](https://developer.squareup.com/docs/orders-api/create-orders#specify-item-quantity-and-measurement-unit).\n\nLine items with a quantity of `0` are automatically removed\nwhen paying for or otherwise completing the order.", "readOnly": false, "required": true }, { "name": "quantity_unit", "type": "#/components/schemas/OrderQuantityUnit", "description": "The measurement unit and decimal precision that this line item's quantity is measured in.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "An optional note associated with the line item.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this line item.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item references.", "readOnly": false, "required": false }, { "name": "variation_name", "type": "string", "description": "The name of the variation applied to this line item.", "readOnly": false, "required": false }, { "name": "item_type", "type": "#/components/schemas/OrderLineItemItemType", "description": "The type of line item: an itemized sale, a non-itemized sale (custom amount), or the\nactivation or reloading of a gift card.\n", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this line item. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "modifiers", "type": "array", "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemModifier" }, { "name": "applied_taxes", "type": "array", "description": "The list of references to taxes applied to this line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a\ntop-level `OrderLineItemTax` applied to the line item. On reads, the\namount applied is populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every line\nitem for all `ORDER` scoped taxes added to the order. `OrderLineItemAppliedTax`\nrecords for `LINE_ITEM` scoped taxes must be added in requests for the tax\nto apply to any line items.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "applied_discounts", "type": "array", "description": "The list of references to discounts applied to this line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderLineItemDiscounts` applied to the line item. On reads, the amount\napplied is populated.\n\nAn `OrderLineItemAppliedDiscount` is automatically created on every line item for all\n`ORDER` scoped discounts that are added to the order. `OrderLineItemAppliedDiscount` records\nfor `LINE_ITEM` scoped discounts must be added in requests for the discount to apply to any\nline items.\n\nTo change the amount of a discount, modify the referenced top-level discount.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedDiscount" }, { "name": "applied_service_charges", "type": "array", "description": "The list of references to service charges applied to this line item. Each\n`OrderLineItemAppliedServiceCharge` has a `service_charge_id` that references the `uid` of a\ntop-level `OrderServiceCharge` applied to the line item. On reads, the amount applied is\npopulated.\n\nTo change the amount of a service charge, modify the referenced top-level service charge.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedServiceCharge" }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for a single unit of the line item.", "readOnly": false, "required": false }, { "name": "variation_total_price_money", "type": "#/components/schemas/Money", "description": "The total price of all item variations sold in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity`.\nIt does not include modifiers.", "readOnly": true, "required": false }, { "name": "gross_sales_money", "type": "#/components/schemas/Money", "description": "The amount of money made in gross sales for this line item.\nThe amount is calculated as the sum of the variation's total price and each modifier's total price.\nFor inclusive tax items in the US, Canada, and Japan, tax is deducted from `gross_sales_money`. For Europe and\nAustralia, inclusive tax remains as part of the gross sale calculation.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the line item.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to collect for the line item.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for this line item.", "readOnly": true, "required": false }, { "name": "pricing_blocklists", "type": "#/components/schemas/OrderLineItemPricingBlocklists", "description": "Describes pricing adjustments that are blocked from automatic\napplication to a line item. For more information, see\n[Apply Taxes and Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).", "readOnly": false, "required": false }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of apportioned service charge money to collect for the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderQuantityUnit", "properties": [ { "name": "measurement_unit", "type": "#/components/schemas/MeasurementUnit", "description": "A [MeasurementUnit](entity:MeasurementUnit) that represents the\nunit of measure for the quantity.", "readOnly": false, "required": false }, { "name": "precision", "type": "integer", "description": "For non-integer quantities, represents the number of digits after the decimal point that are\nrecorded for this quantity.\n\nFor example, a precision of 1 allows quantities such as `\"1.0\"` and `\"1.1\"`, but not `\"1.01\"`.\n\nMin: 0. Max: 5.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing the\n[CatalogMeasurementUnit](entity:CatalogMeasurementUnit).\n\nThis field is set when this is a catalog-backed measurement unit.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this measurement unit references.\n\nThis field is set when this is a catalog-backed measurement unit.", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnit", "properties": [ { "name": "custom_unit", "type": "#/components/schemas/MeasurementUnitCustom", "description": "A custom unit of measurement defined by the seller using the Point of Sale\napp or ad-hoc as an order line item.", "readOnly": false, "required": false }, { "name": "area_unit", "type": "#/components/schemas/MeasurementUnitArea", "description": "Represents a standard area unit.\n", "readOnly": false, "required": false }, { "name": "length_unit", "type": "#/components/schemas/MeasurementUnitLength", "description": "Represents a standard length unit.\n", "readOnly": false, "required": false }, { "name": "volume_unit", "type": "#/components/schemas/MeasurementUnitVolume", "description": "Represents a standard volume unit.\n", "readOnly": false, "required": false }, { "name": "weight_unit", "type": "#/components/schemas/MeasurementUnitWeight", "description": "Represents a standard unit of weight or mass.\n", "readOnly": false, "required": false }, { "name": "generic_unit", "type": "#/components/schemas/MeasurementUnitGeneric", "description": "Reserved for API integrations that lack the ability to specify a real measurement unit\n", "readOnly": false, "required": false }, { "name": "time_unit", "type": "#/components/schemas/MeasurementUnitTime", "description": "Represents a standard unit of time.\n", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/MeasurementUnitUnitType", "description": "Represents the type of the measurement unit.\n", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnitCustom", "properties": [ { "name": "name", "type": "string", "description": "The name of the custom unit, for example \"bushel\".", "readOnly": false, "required": true }, { "name": "abbreviation", "type": "string", "description": "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears\nin the cart for the Point of Sale app, and in reports.", "readOnly": false, "required": true } ] }, { "name": "MeasurementUnitArea", "properties": [] }, { "name": "MeasurementUnitLength", "properties": [] }, { "name": "MeasurementUnitVolume", "properties": [] }, { "name": "MeasurementUnitWeight", "properties": [] }, { "name": "MeasurementUnitGeneric", "properties": [] }, { "name": "MeasurementUnitTime", "properties": [] }, { "name": "MeasurementUnitUnitType", "properties": [] }, { "name": "OrderLineItemItemType", "properties": [] }, { "name": "OrderLineItemModifier", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the modifier only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this modifier references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the item modifier.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0.", "readOnly": false, "required": false }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` will\noverride the predefined [CatalogModifier](entity:CatalogModifier) price.", "readOnly": false, "required": false }, { "name": "total_price_money", "type": "#/components/schemas/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "OrderLineItemAppliedTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied tax only within this order.", "readOnly": false, "required": false }, { "name": "tax_uid", "type": "string", "description": "The `uid` of the tax for which this applied tax represents. It must reference\na tax present in the `order.taxes` field.\n\nThis field is immutable. To change which taxes apply to a line item, delete and add a new\n`OrderLineItemAppliedTax`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the tax to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemAppliedDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied discount only within this order.", "readOnly": false, "required": false }, { "name": "discount_uid", "type": "string", "description": "The `uid` of the discount that the applied discount represents. It must\nreference a discount present in the `order.discounts` field.\n\nThis field is immutable. To change which discounts apply to a line item,\nyou must delete the discount and re-add it as a new `OrderLineItemAppliedDiscount`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the discount to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemAppliedServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied service charge only within this order.", "readOnly": false, "required": false }, { "name": "service_charge_uid", "type": "string", "description": "The `uid` of the service charge that the applied service charge represents. It must\nreference a service charge present in the `order.service_charges` field.\n\nThis field is immutable. To change which service charges apply to a line item,\ndelete and add a new `OrderLineItemAppliedServiceCharge`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the service charge to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemPricingBlocklists", "properties": [ { "name": "blocked_discounts", "type": "array", "description": "A list of discounts blocked from applying to the line item.\nDiscounts can be blocked by the `discount_uid` (for ad hoc discounts) or\nthe `discount_catalog_object_id` (for catalog discounts).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemPricingBlocklistsBlockedDiscount" }, { "name": "blocked_taxes", "type": "array", "description": "A list of taxes blocked from applying to the line item.\nTaxes can be blocked by the `tax_uid` (for ad hoc taxes) or\nthe `tax_catalog_object_id` (for catalog taxes).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemPricingBlocklistsBlockedTax" } ] }, { "name": "OrderLineItemPricingBlocklistsBlockedDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID of the `BlockedDiscount` within the order.", "readOnly": false, "required": false }, { "name": "discount_uid", "type": "string", "description": "The `uid` of the discount that should be blocked. Use this field to block\nad hoc discounts. For catalog discounts, use the `discount_catalog_object_id` field.", "readOnly": false, "required": false }, { "name": "discount_catalog_object_id", "type": "string", "description": "The `catalog_object_id` of the discount that should be blocked.\nUse this field to block catalog discounts. For ad hoc discounts, use the\n`discount_uid` field.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItemPricingBlocklistsBlockedTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID of the `BlockedTax` within the order.", "readOnly": false, "required": false }, { "name": "tax_uid", "type": "string", "description": "The `uid` of the tax that should be blocked. Use this field to block\nad hoc taxes. For catalog, taxes use the `tax_catalog_object_id` field.", "readOnly": false, "required": false }, { "name": "tax_catalog_object_id", "type": "string", "description": "The `catalog_object_id` of the tax that should be blocked.\nUse this field to block catalog taxes. For ad hoc taxes, use the\n`tax_uid` field.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItemTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the tax only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this tax references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The tax's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal\nnumber. For example, a value of `\"7.25\"` corresponds to a percentage of\n7.25%.", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this tax. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the tax.\n\n- For percentage-based taxes, `applied_money` is the money\ncalculated using the percentage.", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemTaxScope", "description": "Indicates the level at which the tax applies. For `ORDER` scoped taxes,\nSquare generates references in `applied_taxes` on all order line items that do\nnot have them. For `LINE_ITEM` scoped taxes, the tax only applies to line items\nwith references in their `applied_taxes` field.\n\nThis field is immutable. To change the scope, you must delete the tax and\nre-add it as a new tax.\n", "readOnly": false, "required": false }, { "name": "auto_applied", "type": "boolean", "description": "Determines whether the tax was automatically applied to the order based on\nthe catalog configuration. For an example, see\n[Automatically Apply Taxes to an Order](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes).", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemTaxType", "properties": [] }, { "name": "OrderLineItemTaxScope", "properties": [] }, { "name": "OrderLineItemDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the discount only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this discount references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The discount's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemDiscountType", "description": "The type of the discount.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the discount, as a string representation of a decimal number.\nA value of `7.25` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of discount actually applied to the line item.\n\nThe amount represents the amount of money applied as a line-item scoped discount.\nWhen an amount-based discount is scoped to the entire order, the value\nof `applied_money` is different than `amount_money` because the total\namount of the discount is distributed across all line items.", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this discount. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemDiscountScope", "description": "Indicates the level at which the discount applies. For `ORDER` scoped discounts,\nSquare generates references in `applied_discounts` on all order line items that do\nnot have them. For `LINE_ITEM` scoped discounts, the discount only applies to line items\nwith a discount reference in their `applied_discounts` field.\n\nThis field is immutable. To change the scope of a discount, you must delete\nthe discount and re-add it as a new discount.\n", "readOnly": false, "required": false }, { "name": "reward_ids", "type": "array", "description": "The reward IDs corresponding to this discount. The application and\nspecification of discounts that have `reward_ids` are completely controlled by the backing\ncriteria corresponding to the reward tiers of the rewards that are added to the order\nthrough the Loyalty API. To manually unapply discounts that are the result of added rewards,\nthe rewards must be removed from the order through the Loyalty API.", "readOnly": true, "required": false }, { "name": "pricing_rule_id", "type": "string", "description": "The object ID of a [pricing rule](entity:CatalogPricingRule) to be applied\nautomatically to this discount. The specification and application of the discounts, to\nwhich a `pricing_rule_id` is assigned, are completely controlled by the corresponding\npricing rule.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemDiscountType", "properties": [] }, { "name": "OrderLineItemDiscountScope", "properties": [] }, { "name": "OrderServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the service charge only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the service charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing the service charge [CatalogObject](entity:CatalogObject).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this service charge references.", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The service charge percentage as a string representation of a\ndecimal number. For example, `\"7.25\"` indicates a service charge of 7.25%.\n\nExactly 1 of `percentage` or `amount_money` should be set.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of a non-percentage-based service charge.\n\nExactly one of `percentage` or `amount_money` should be set.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the service charge,\nincluding any inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money\ncalculated using the percentage.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the service charge.\n\n__Note__: If an inclusive tax is applied to the service charge,\n`total_money` does not equal `applied_money` plus `total_tax_money`\nbecause the inclusive tax amount is already included in both\n`applied_money` and `total_tax_money`.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/OrderServiceChargeCalculationPhase", "description": "The calculation phase at which to apply the service charge.\n", "readOnly": false, "required": false }, { "name": "taxable", "type": "boolean", "description": "Indicates whether the service charge can be taxed. If set to `true`,\norder-level taxes automatically apply to the service charge. Note that\nservice charges calculated in the `TOTAL_PHASE` cannot be marked as taxable.", "readOnly": false, "required": false }, { "name": "applied_taxes", "type": "array", "description": "The list of references to the taxes applied to this service charge. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderLineItemTax` that is being applied to this service charge. On reads, the amount applied\nis populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every taxable service charge\nfor all `ORDER` scoped taxes that are added to the order. `OrderLineItemAppliedTax` records\nfor `LINE_ITEM` scoped taxes must be added in requests for the tax to apply to any taxable\nservice charge. Taxable service charges have the `taxable` field set to `true` and calculated\nin the `SUBTOTAL_PHASE`.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this service charge. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderServiceChargeType", "description": "The type of the service charge.\n", "readOnly": true, "required": false }, { "name": "treatment_type", "type": "#/components/schemas/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\n", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\n", "readOnly": false, "required": false } ] }, { "name": "OrderServiceChargeCalculationPhase", "properties": [] }, { "name": "OrderServiceChargeType", "properties": [] }, { "name": "OrderServiceChargeTreatmentType", "properties": [] }, { "name": "OrderServiceChargeScope", "properties": [] }, { "name": "Fulfillment", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the fulfillment only within this order.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/FulfillmentType", "description": "The type of the fulfillment.\n", "readOnly": false, "required": false }, { "name": "state", "type": "#/components/schemas/FulfillmentState", "description": "The state of the fulfillment.\n", "readOnly": false, "required": false }, { "name": "line_item_application", "type": "#/components/schemas/FulfillmentFulfillmentLineItemApplication", "description": "Describes what order line items this fulfillment applies to.\nIt can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.\n", "readOnly": true, "required": false }, { "name": "entries", "type": "array", "description": "A list of entries pertaining to the fulfillment of an order. Each entry must reference\na valid `uid` for an order line item in the `line_item_uid` field, as well as a `quantity` to\nfulfill.\n\nMultiple entries can reference the same line item `uid`, as long as the total quantity among\nall fulfillment entries referencing a single line item does not exceed the quantity of the\norder's line item itself.\n\nAn order cannot be marked as `COMPLETED` before all fulfillments are `COMPLETED`,\n`CANCELED`, or `FAILED`. Fulfillments can be created and completed independently\nbefore order completion.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/FulfillmentFulfillmentEntry" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this fulfillment. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "pickup_details", "type": "#/components/schemas/FulfillmentPickupDetails", "description": "Contains details for a pickup fulfillment. These details are required when the fulfillment\ntype is `PICKUP`.", "readOnly": false, "required": false }, { "name": "shipment_details", "type": "#/components/schemas/FulfillmentShipmentDetails", "description": "Contains details for a shipment fulfillment. These details are required when the fulfillment type\nis `SHIPMENT`.\n\nA shipment fulfillment's relationship to fulfillment `state`:\n`PROPOSED`: A shipment is requested.\n`RESERVED`: Fulfillment in progress. Shipment processing.\n`PREPARED`: Shipment packaged. Shipping label created.\n`COMPLETED`: Package has been shipped.\n`CANCELED`: Shipment has been canceled.\n`FAILED`: Shipment has failed.", "readOnly": false, "required": false }, { "name": "delivery_details", "type": "#/components/schemas/FulfillmentDeliveryDetails", "description": "Describes delivery details of an order fulfillment.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentType", "properties": [] }, { "name": "FulfillmentState", "properties": [] }, { "name": "FulfillmentFulfillmentLineItemApplication", "properties": [] }, { "name": "FulfillmentFulfillmentEntry", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the fulfillment entry only within this order.", "readOnly": false, "required": false }, { "name": "line_item_uid", "type": "string", "description": "The `uid` from the order line item.", "readOnly": false, "required": true }, { "name": "quantity", "type": "string", "description": "The quantity of the line item being fulfilled, formatted as a decimal number.\nFor example, `\"3\"`.\n\nFulfillments for line items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "readOnly": false, "required": true }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this fulfillment entry. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false } ] }, { "name": "FulfillmentPickupDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "Information about the person to pick up this fulfillment from a physical\nlocation.", "readOnly": false, "required": false }, { "name": "expires_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment expires if it is not marked in progress. The timestamp must be\nin RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\"). The expiration time can only be set\nup to 7 days in the future. If `expires_at` is not set, any new payments attached to the order\nare automatically completed.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "auto_complete_duration", "type": "string", "description": "The duration of time after which an in progress pickup fulfillment is automatically moved\nto the `COMPLETED` state. The duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nIf not set, this pickup fulfillment remains in progress until it is canceled or completed.\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "schedule_type", "type": "#/components/schemas/FulfillmentPickupDetailsScheduleType", "description": "The schedule type of the pickup fulfillment. Defaults to `SCHEDULED`.\n", "readOnly": false, "required": false }, { "name": "pickup_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the pickup window. Must be in RFC 3339 timestamp format, e.g.,\n\"2016-09-04T23:59:33.123Z\".\n\nFor fulfillments with the schedule type `ASAP`, this is automatically set\nto the current time plus the expected duration to prepare the fulfillment.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "pickup_window_duration", "type": "string", "description": "The window of time in which the order should be picked up after the `pickup_at` timestamp.\nMust be in RFC 3339 duration format, e.g., \"P1W3D\". Can be used as an\ninformational guideline for merchants.\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "prep_time_duration", "type": "string", "description": "The duration of time it takes to prepare this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "A note to provide additional instructions about the pickup\nfulfillment displayed in the Square Point of Sale application and set by the API.", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "accepted_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was marked in progress. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "rejected_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "ready_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment is marked as ready for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "expired_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment expired. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "picked_up_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was picked up by the recipient. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "string", "description": "A description of why the pickup was canceled. The maximum length: 100 characters.", "readOnly": false, "required": false }, { "name": "is_curbside_pickup", "type": "boolean", "description": "If set to `true`, indicates that this pickup order is for curbside pickup, not in-store pickup.", "readOnly": false, "required": false }, { "name": "curbside_pickup_details", "type": "#/components/schemas/FulfillmentPickupDetailsCurbsidePickupDetails", "description": "Specific details for curbside pickup. These details can only be populated if `is_curbside_pickup` is set to `true`.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentRecipient", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer associated with the fulfillment.\n\nIf `customer_id` is provided, the fulfillment recipient's `display_name`,\n`email_address`, and `phone_number` are automatically populated from the\ntargeted customer profile. If these fields are set in the request, the request\nvalues override the information from the customer profile. If the\ntargeted customer profile does not contain the necessary information and\nthese fields are left unset, the request results in an error.", "readOnly": false, "required": false }, { "name": "display_name", "type": "string", "description": "The display name of the fulfillment recipient. This field is required.\n\nIf provided, the display name overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "email_address", "type": "string", "description": "The email address of the fulfillment recipient.\n\nIf provided, the email address overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number of the fulfillment recipient. This field is required.\n\nIf provided, the phone number overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The address of the fulfillment recipient. This field is required.\n\nIf provided, the address overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "FulfillmentPickupDetailsScheduleType", "properties": [] }, { "name": "FulfillmentPickupDetailsCurbsidePickupDetails", "properties": [ { "name": "curbside_details", "type": "string", "description": "Specific details for curbside pickup, such as parking number and vehicle model.", "readOnly": false, "required": false }, { "name": "buyer_arrived_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the buyer arrived and is waiting for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false } ] }, { "name": "FulfillmentShipmentDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "Information about the person to receive this shipment fulfillment.", "readOnly": false, "required": false }, { "name": "carrier", "type": "string", "description": "The shipping carrier being used to ship this fulfillment (such as UPS, FedEx, or USPS).", "readOnly": false, "required": false }, { "name": "shipping_note", "type": "string", "description": "A note with additional information for the shipping carrier.", "readOnly": false, "required": false }, { "name": "shipping_type", "type": "string", "description": "A description of the type of shipping product purchased from the carrier\n(such as First Class, Priority, or Express).", "readOnly": false, "required": false }, { "name": "tracking_number", "type": "string", "description": "The reference number provided by the carrier to track the shipment's progress.", "readOnly": false, "required": false }, { "name": "tracking_url", "type": "string", "description": "A link to the tracking webpage on the carrier's website.", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment was requested. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "in_progress_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `RESERVED` state, which indicates that preparation\nof this shipment has begun. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "packaged_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `PREPARED` state, which indicates that the\nfulfillment is packaged. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "expected_shipped_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment is expected to be delivered to the shipping carrier.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "shipped_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `COMPLETED` state, which indicates that\nthe fulfillment has been given to the shipping carrier. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating the shipment was canceled.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "cancel_reason", "type": "string", "description": "A description of why the shipment was canceled.", "readOnly": false, "required": false }, { "name": "failed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment failed to be completed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "failure_reason", "type": "string", "description": "A description of why the shipment failed to be completed.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentDeliveryDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "The contact information for the person to receive the fulfillment.", "readOnly": false, "required": false }, { "name": "schedule_type", "type": "#/components/schemas/FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType", "description": "Indicates the fulfillment delivery schedule type. If `SCHEDULED`, then\n`deliver_at` is required. If `ASAP`, then `prep_time_duration` is required. The default is `SCHEDULED`.\n", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nMust be in RFC 3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "deliver_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the delivery period.\nWhen the fulfillment `schedule_type` is `ASAP`, the field is automatically\nset to the current time plus the `prep_time_duration`.\nOtherwise, the application can set this field while the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the\nterminal state such as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "prep_time_duration", "type": "string", "description": "The duration of time it takes to prepare and deliver this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "delivery_window_duration", "type": "string", "description": "The time period after `deliver_at` in which to deliver the order.\nApplications can set this field when the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the terminal state\nsuch as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "Provides additional instructions about the delivery fulfillment.\nIt is displayed in the Square Point of Sale application and set by the API.", "readOnly": false, "required": false }, { "name": "completed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller completed the fulfillment.\nThis field is automatically set when fulfillment `state` changes to `COMPLETED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "in_progress_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller started processing the fulfillment.\nThis field is automatically set when the fulfillment `state` changes to `RESERVED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "rejected_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. This field is\nautomatically set when the fulfillment `state` changes to `FAILED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "ready_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the seller marked the fulfillment as ready for\ncourier pickup. This field is automatically set when the fulfillment `state` changes\nto PREPARED.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "delivered_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was delivered to the recipient.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. This field is automatically\nset when the fulfillment `state` changes to `CANCELED`.\n\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "string", "description": "The delivery cancellation reason. Max length: 100 characters.", "readOnly": false, "required": false }, { "name": "courier_pickup_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when an order can be picked up by the courier for delivery.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "courier_pickup_window_duration", "type": "string", "description": "The time period after `courier_pickup_at` in which the courier should pick up the order.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "is_no_contact_delivery", "type": "boolean", "description": "Whether the delivery is preferred to be no contact.", "readOnly": false, "required": false }, { "name": "dropoff_notes", "type": "string", "description": "A note to provide additional instructions about how to deliver the order.", "readOnly": false, "required": false }, { "name": "courier_provider_name", "type": "string", "description": "The name of the courier provider.", "readOnly": false, "required": false }, { "name": "courier_support_phone_number", "type": "string", "description": "The support phone number of the courier.", "readOnly": false, "required": false }, { "name": "square_delivery_id", "type": "string", "description": "The identifier for the delivery created by Square.", "readOnly": false, "required": false }, { "name": "external_delivery_id", "type": "string", "description": "The identifier for the delivery created by the third-party courier service.", "readOnly": false, "required": false }, { "name": "managed_delivery", "type": "boolean", "description": "The flag to indicate the delivery is managed by a third party (ie DoorDash), which means\nwe may not receive all recipient information for PII purposes.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType", "properties": [] }, { "name": "OrderReturn", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return only within this order.", "readOnly": false, "required": false }, { "name": "source_order_id", "type": "string", "description": "An order that contains the original sale of these return line items. This is unset\nfor unlinked returns.", "readOnly": false, "required": false }, { "name": "return_line_items", "type": "array", "description": "A collection of line items that are being returned.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnLineItem" }, { "name": "return_service_charges", "type": "array", "description": "A collection of service charges that are being returned.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnServiceCharge" }, { "name": "return_taxes", "type": "array", "description": "A collection of references to taxes being returned for an order, including the total\napplied tax amount to be returned. The taxes must reference a top-level tax ID from the source\norder.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturnTax" }, { "name": "return_discounts", "type": "array", "description": "A collection of references to discounts being returned for an order, including the total\napplied discount amount to be returned. The discounts must reference a top-level discount ID\nfrom the source order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturnDiscount" }, { "name": "return_tips", "type": "array", "description": "A collection of references to tips being returned for an order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnTip" }, { "name": "rounding_adjustment", "type": "#/components/schemas/OrderRoundingAdjustment", "description": "A positive or negative rounding adjustment to the total value being returned. Adjustments are commonly\nused to apply cash rounding when the minimum unit of the account is smaller than the lowest\nphysical denomination of the currency.", "readOnly": false, "required": false }, { "name": "return_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "An aggregate monetary value being returned by this return entry.", "readOnly": false, "required": false } ] }, { "name": "OrderReturnLineItem", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID for this return line-item entry.", "readOnly": false, "required": false }, { "name": "source_line_item_uid", "type": "string", "description": "The `uid` of the line item in the original sale order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the line item.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity returned, formatted as a decimal number.\nFor example, `\"3\"`.\n\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "readOnly": false, "required": true }, { "name": "quantity_unit", "type": "#/components/schemas/OrderQuantityUnit", "description": "The unit and precision that this return line item's quantity is measured in.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "The note of the return line item.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this return line item.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item references.", "readOnly": false, "required": false }, { "name": "variation_name", "type": "string", "description": "The name of the variation applied to this return line item.", "readOnly": false, "required": false }, { "name": "item_type", "type": "#/components/schemas/OrderLineItemItemType", "description": "The type of line item: an itemized return, a non-itemized return (custom amount),\nor the return of an unactivated gift card sale.\n", "readOnly": false, "required": false }, { "name": "return_modifiers", "type": "array", "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnLineItemModifier" }, { "name": "applied_taxes", "type": "array", "description": "The list of references to `OrderReturnTax` entities applied to the return line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderReturnTax` applied to the return line item. On reads, the applied amount\nis populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "applied_discounts", "type": "array", "description": "The list of references to `OrderReturnDiscount` entities applied to the return line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderReturnDiscount` applied to the return line item. On reads, the applied amount\nis populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedDiscount" }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for a single unit of the line item.", "readOnly": false, "required": false }, { "name": "variation_total_price_money", "type": "#/components/schemas/Money", "description": "The total price of all item variations returned in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity` and\ndoes not include modifiers.", "readOnly": true, "required": false }, { "name": "gross_return_money", "type": "#/components/schemas/Money", "description": "The gross return amount of money calculated as (item base price + modifiers price) * quantity.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to return for the line item.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to return for the line item.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to return for this line item.", "readOnly": true, "required": false }, { "name": "applied_service_charges", "type": "array", "description": "The list of references to `OrderReturnServiceCharge` entities applied to the return\nline item. Each `OrderLineItemAppliedServiceCharge` has a `service_charge_uid` that\nreferences the `uid` of a top-level `OrderReturnServiceCharge` applied to the return line\nitem. On reads, the applied amount is populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedServiceCharge" }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of apportioned service charge money to return for the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderReturnLineItemModifier", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return modifier only within this order.", "readOnly": false, "required": false }, { "name": "source_modifier_uid", "type": "string", "description": "The modifier `uid` from the order's line item that contains the\noriginal sale of this line item modifier.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item modifier references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the item modifier.", "readOnly": false, "required": false }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` overrides the predefined [CatalogModifier](entity:CatalogModifier) price.", "readOnly": false, "required": false }, { "name": "total_price_money", "type": "#/components/schemas/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0.", "readOnly": false, "required": false } ] }, { "name": "OrderReturnServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return service charge only within this order.", "readOnly": false, "required": false }, { "name": "source_service_charge_uid", "type": "string", "description": "The service charge `uid` from the order containing the original\nservice charge. `source_service_charge_uid` is `null` for\nunlinked returns.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the service charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID of the associated [OrderServiceCharge](entity:OrderServiceCharge).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this service charge references.", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "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%.\n\nEither `percentage` or `amount_money` should be set, but not both.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of a non-percentage-based service charge.\n\nEither `percentage` or `amount_money` should be set, but not both.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the service charge, including\nany inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money calculated using the percentage.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the service charge.\n\n__NOTE__: If an inclusive tax is applied to the service charge, `total_money`\ndoes not equal `applied_money` plus `total_tax_money` because the inclusive\ntax amount is already included in both `applied_money` and `total_tax_money`.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/OrderServiceChargeCalculationPhase", "description": "The calculation phase after which to apply the service charge.\n", "readOnly": true, "required": false }, { "name": "taxable", "type": "boolean", "description": "Indicates whether the surcharge can be taxed. Service charges\ncalculated in the `TOTAL_PHASE` cannot be marked as taxable.", "readOnly": false, "required": false }, { "name": "applied_taxes", "type": "array", "description": "The list of references to `OrderReturnTax` entities applied to the\n`OrderReturnServiceCharge`. Each `OrderLineItemAppliedTax` has a `tax_uid`\nthat references the `uid` of a top-level `OrderReturnTax` that is being\napplied to the `OrderReturnServiceCharge`. On reads, the applied amount is\npopulated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "treatment_type", "type": "#/components/schemas/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\n", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the returned tax only within this order.", "readOnly": false, "required": false }, { "name": "source_tax_uid", "type": "string", "description": "The tax `uid` from the order that contains the original tax charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this tax references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The tax's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal number.\nFor example, a value of `\"7.25\"` corresponds to a percentage of 7.25%.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the tax in an order.", "readOnly": true, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemTaxScope", "description": "Indicates the level at which the `OrderReturnTax` applies. For `ORDER` scoped\ntaxes, Square generates references in `applied_taxes` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the returned discount only within this order.", "readOnly": false, "required": false }, { "name": "source_discount_uid", "type": "string", "description": "The discount `uid` from the order that contains the original application of this discount.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this discount references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The discount's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemDiscountType", "description": "The type of the discount. If it is created by the API, it is `FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal number.\nA value of `\"7.25\"` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of discount actually applied to this line item. When an amount-based\ndiscount is at the order level, this value is different from `amount_money` because the discount\nis distributed across the line items.", "readOnly": true, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemDiscountScope", "description": "Indicates the level at which the `OrderReturnDiscount` applies. For `ORDER` scoped\ndiscounts, the server generates references in `applied_discounts` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the discount is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnTip", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the tip only within this order.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of tip being returned\n--", "readOnly": true, "required": false }, { "name": "source_tender_uid", "type": "string", "description": "The tender `uid` from the order that contains the original application of this tip.", "readOnly": false, "required": false }, { "name": "source_tender_id", "type": "string", "description": "The tender `id` from the order that contains the original application of this tip.", "readOnly": false, "required": false } ] }, { "name": "OrderRoundingAdjustment", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the rounding adjustment only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the rounding adjustment from the original sale order.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The actual rounding adjustment amount.", "readOnly": false, "required": false } ] }, { "name": "OrderMoneyAmounts", "properties": [ { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total money.", "readOnly": false, "required": false }, { "name": "tax_money", "type": "#/components/schemas/Money", "description": "The money associated with taxes.", "readOnly": false, "required": false }, { "name": "discount_money", "type": "#/components/schemas/Money", "description": "The money associated with discounts.", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The money associated with tips.", "readOnly": false, "required": false }, { "name": "service_charge_money", "type": "#/components/schemas/Money", "description": "The money associated with service charges.", "readOnly": false, "required": false } ] }, { "name": "Tender", "properties": [ { "name": "id", "type": "string", "description": "The tender's unique ID. It is the associated payment ID.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the transaction's associated location.", "readOnly": false, "required": false }, { "name": "transaction_id", "type": "string", "description": "The ID of the tender's associated transaction.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp for when the tender was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "note", "type": "string", "description": "An optional note associated with the tender at the time of payment.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total amount of the tender, including `tip_money`. If the tender has a `payment_id`,\nthe `total_money` of the corresponding [Payment](entity:Payment) will be equal to the\n`amount_money` of the tender.", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The tip's amount of the tender.", "readOnly": false, "required": false }, { "name": "processing_fee_money", "type": "#/components/schemas/Money", "description": "The amount of any Square processing fees applied to the tender.\n\nThis field is not immediately populated when a new transaction is created.\nIt is usually available after about ten seconds.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "If the tender is associated with a customer or represents a customer's card on file,\nthis is the ID of the associated customer.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/TenderType", "description": "The type of tender, such as `CARD` or `CASH`.\n", "readOnly": false, "required": true }, { "name": "card_details", "type": "#/components/schemas/TenderCardDetails", "description": "The details of the card tender.\n\nThis value is present only if the value of `type` is `CARD`.", "readOnly": false, "required": false }, { "name": "cash_details", "type": "#/components/schemas/TenderCashDetails", "description": "The details of the cash tender.\n\nThis value is present only if the value of `type` is `CASH`.", "readOnly": false, "required": false }, { "name": "bank_account_details", "type": "#/components/schemas/TenderBankAccountDetails", "description": "The details of the bank account tender.\n\nThis value is present only if the value of `type` is `BANK_ACCOUNT`.", "readOnly": false, "required": false }, { "name": "buy_now_pay_later_details", "type": "#/components/schemas/TenderBuyNowPayLaterDetails", "description": "The details of a Buy Now Pay Later tender.\n\nThis value is present only if the value of `type` is `BUY_NOW_PAY_LATER`.", "readOnly": false, "required": false }, { "name": "square_account_details", "type": "#/components/schemas/TenderSquareAccountDetails", "description": "The details of a Square Account tender.\n\nThis value is present only if the value of `type` is `SQUARE_ACCOUNT`.", "readOnly": false, "required": false }, { "name": "additional_recipients", "type": "array", "description": "Additional recipients (other than the merchant) receiving a portion of this tender.\nFor example, fees assessed on the purchase by a third party integration.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/AdditionalRecipient" }, { "name": "payment_id", "type": "string", "description": "The ID of the [Payment](entity:Payment) that corresponds to this tender.\nThis value is only present for payments created with the v2 Payments API.", "readOnly": false, "required": false } ] }, { "name": "TenderType", "properties": [] }, { "name": "TenderCardDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderCardDetailsStatus", "description": "The credit card payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderCardDetailsStatus](entity:TenderCardDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false }, { "name": "card", "type": "#/components/schemas/Card", "description": "The credit card's non-confidential details.", "readOnly": false, "required": false }, { "name": "entry_method", "type": "#/components/schemas/TenderCardDetailsEntryMethod", "description": "The method used to enter the card's details for the transaction.\n", "readOnly": false, "required": false } ] }, { "name": "TenderCardDetailsStatus", "properties": [] }, { "name": "Card", "properties": [ { "name": "id", "type": "string", "description": "Unique ID for this card. Generated by Square.", "readOnly": true, "required": false }, { "name": "card_brand", "type": "#/components/schemas/CardBrand", "description": "The card's brand.\n", "readOnly": true, "required": false }, { "name": "last_4", "type": "string", "description": "The last 4 digits of the card number.", "readOnly": true, "required": false }, { "name": "exp_month", "type": "integer", "description": "The expiration month of the associated card as an integer between 1 and 12.", "readOnly": false, "required": false }, { "name": "exp_year", "type": "integer", "description": "The four-digit year of the card's expiration date.", "readOnly": false, "required": false }, { "name": "cardholder_name", "type": "string", "description": "The name of the cardholder.", "readOnly": false, "required": false }, { "name": "billing_address", "type": "#/components/schemas/Address", "description": "The billing address for this card.", "readOnly": false, "required": false }, { "name": "fingerprint", "type": "string", "description": "Intended as a Square-assigned identifier, based\non the card number, to identify the card across multiple locations within a\nsingle application.", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "**Required** The ID of a customer created using the Customers API to be associated with the card.", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the merchant associated with the card.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional user-defined reference ID that associates this card with\nanother entity in an external system. For example, a customer ID from an\nexternal customer management system.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "Indicates whether or not a card can be used for payments.", "readOnly": true, "required": false }, { "name": "card_type", "type": "#/components/schemas/CardType", "description": "The type of the card.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "prepaid_type", "type": "#/components/schemas/CardPrepaidType", "description": "Indicates whether the Card is prepaid or not.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "bin", "type": "string", "description": "The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API\nreturns this field.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "Current version number of the card. Increments with each card update. Requests to update an\nexisting Card object will be rejected unless the version in the request matches the current\nversion for the Card.", "readOnly": false, "required": false }, { "name": "card_co_brand", "type": "#/components/schemas/CardCoBrand", "description": "The card's co-brand if available. For example, an Afterpay virtual card would have a\nco-brand of AFTERPAY.\n", "readOnly": true, "required": false } ] }, { "name": "CardBrand", "properties": [] }, { "name": "CardType", "properties": [] }, { "name": "CardPrepaidType", "properties": [] }, { "name": "CardCoBrand", "properties": [] }, { "name": "TenderCardDetailsEntryMethod", "properties": [] }, { "name": "TenderCashDetails", "properties": [ { "name": "buyer_tendered_money", "type": "#/components/schemas/Money", "description": "The total amount of cash provided by the buyer, before change is given.", "readOnly": false, "required": false }, { "name": "change_back_money", "type": "#/components/schemas/Money", "description": "The amount of change returned to the buyer.", "readOnly": false, "required": false } ] }, { "name": "TenderBankAccountDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderBankAccountDetailsStatus", "description": "The bank account payment's current state.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "TenderBankAccountDetailsStatus", "properties": [] }, { "name": "TenderBuyNowPayLaterDetails", "properties": [ { "name": "buy_now_pay_later_brand", "type": "#/components/schemas/TenderBuyNowPayLaterDetailsBrand", "description": "The Buy Now Pay Later brand.\n", "readOnly": true, "required": false }, { "name": "status", "type": "#/components/schemas/TenderBuyNowPayLaterDetailsStatus", "description": "The buy now pay later payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderBuyNowPayLaterDetailsStatus](entity:TenderBuyNowPayLaterDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false } ] }, { "name": "TenderBuyNowPayLaterDetailsBrand", "properties": [] }, { "name": "TenderBuyNowPayLaterDetailsStatus", "properties": [] }, { "name": "TenderSquareAccountDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderSquareAccountDetailsStatus", "description": "The Square Account payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderSquareAccountDetailsStatus](entity:TenderSquareAccountDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false } ] }, { "name": "TenderSquareAccountDetailsStatus", "properties": [] }, { "name": "AdditionalRecipient", "properties": [ { "name": "location_id", "type": "string", "description": "The location ID for a recipient (other than the merchant) receiving a portion of this tender.", "readOnly": false, "required": true }, { "name": "description", "type": "string", "description": "The description of the additional recipient.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money distributed to the recipient.", "readOnly": false, "required": true }, { "name": "receivable_id", "type": "string", "description": "The unique ID for the RETIRED `AdditionalRecipientReceivable` object. This field should be empty for any `AdditionalRecipient` objects created after the retirement.", "readOnly": false, "required": false } ] }, { "name": "Refund", "properties": [ { "name": "id", "type": "string", "description": "The refund's unique ID.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The ID of the refund's associated location.", "readOnly": false, "required": true }, { "name": "transaction_id", "type": "string", "description": "The ID of the transaction that the refunded tender is part of.", "readOnly": false, "required": false }, { "name": "tender_id", "type": "string", "description": "The ID of the refunded tender.", "readOnly": false, "required": true }, { "name": "created_at", "type": "string", "description": "The timestamp for when the refund was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "reason", "type": "string", "description": "The reason for the refund being issued.", "readOnly": false, "required": true }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money refunded to the buyer.", "readOnly": false, "required": true }, { "name": "status", "type": "#/components/schemas/RefundStatus", "description": "The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`,\nor `FAILED`).\n", "readOnly": false, "required": true }, { "name": "processing_fee_money", "type": "#/components/schemas/Money", "description": "The amount of Square processing fee money refunded to the *merchant*.", "readOnly": false, "required": false }, { "name": "additional_recipients", "type": "array", "description": "Additional recipients (other than the merchant) receiving a portion of this refund.\nFor example, fees assessed on a refund of a purchase by a third party integration.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/AdditionalRecipient" } ] }, { "name": "RefundStatus", "properties": [] }, { "name": "OrderState", "properties": [] }, { "name": "OrderPricingOptions", "properties": [ { "name": "auto_apply_discounts", "type": "boolean", "description": "The option to determine whether pricing rule-based\ndiscounts are automatically applied to an order.", "readOnly": false, "required": false }, { "name": "auto_apply_taxes", "type": "boolean", "description": "The option to determine whether rule-based taxes are automatically\napplied to an order when the criteria of the corresponding rules are met.", "readOnly": false, "required": false } ] }, { "name": "OrderReward", "properties": [ { "name": "id", "type": "string", "description": "The identifier of the reward.", "readOnly": false, "required": true }, { "name": "reward_tier_id", "type": "string", "description": "The identifier of the reward tier corresponding to this reward.", "readOnly": false, "required": true } ] } ], "BatchRetrieveOrdersRequest": [ { "name": "BatchRetrieveOrdersRequest", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the location for these orders. This field is optional: omit it to retrieve\norders within the scope of the current authorization's merchant ID.", "readOnly": false, "required": false }, { "name": "order_ids", "type": "array", "description": "The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request.", "readOnly": false, "required": true } ] } ], "CalculateOrderRequest": [ { "name": "CalculateOrderRequest", "properties": [ { "name": "order", "type": "#/components/schemas/Order", "description": "The order to be calculated. Expects the entire order, not a sparse update.", "readOnly": false, "required": true }, { "name": "proposed_rewards", "type": "array", "description": "Identifies one or more loyalty reward tiers to apply during the order calculation.\nThe discounts defined by the reward tiers are added to the order only to preview the\neffect of applying the specified rewards. The rewards do not correspond to actual\nredemptions; that is, no `reward`s are created. Therefore, the reward `id`s are\nrandom strings used only to reference the reward tier.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReward" } ] }, { "name": "Order", "properties": [ { "name": "id", "type": "string", "description": "The order's unique ID.", "readOnly": true, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the seller location that this order is associated with.", "readOnly": false, "required": true }, { "name": "reference_id", "type": "string", "description": "A client-specified ID to associate an entity in another system\nwith this order.", "readOnly": false, "required": false }, { "name": "source", "type": "#/components/schemas/OrderSource", "description": "The origination details of the order.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the [customer](entity:Customer) associated with the order.\n\nYou should specify a `customer_id` on the order (or the payment) to ensure that transactions\nare reliably linked to customers. Omitting this field might result in the creation of new\n[instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles).", "readOnly": false, "required": false }, { "name": "line_items", "type": "array", "description": "The line items included in the order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItem" }, { "name": "taxes", "type": "array", "description": "The list of all taxes associated with the order.\n\nTaxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an\n`OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes\nwith `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item.\n\nOn reads, each tax in the list includes the total amount of that tax applied to the order.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated\n`line_items.taxes` field results in an error. Use `line_items.applied_taxes`\ninstead.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemTax" }, { "name": "discounts", "type": "array", "description": "The list of all discounts associated with the order.\n\nDiscounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`,\nan `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to.\nFor discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount`\nfor every line item.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated\n`line_items.discounts` field results in an error. Use `line_items.applied_discounts`\ninstead.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemDiscount" }, { "name": "service_charges", "type": "array", "description": "A list of service charges applied to the order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderServiceCharge" }, { "name": "fulfillments", "type": "array", "description": "Details about order fulfillment.\n\nOrders can only be created with at most one fulfillment. However, orders returned\nby the API might contain multiple fulfillments.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Fulfillment" }, { "name": "returns", "type": "array", "description": "A collection of items from sale orders being returned in this one. Normally part of an\nitemized return or exchange. There is exactly one `Return` object per sale `Order` being\nreferenced.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturn" }, { "name": "return_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "The rollup of the returned money amounts.", "readOnly": true, "required": false }, { "name": "net_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "The net money amounts (sale money - return money).", "readOnly": true, "required": false }, { "name": "rounding_adjustment", "type": "#/components/schemas/OrderRoundingAdjustment", "description": "A positive rounding adjustment to the total of the order. This adjustment is commonly\nused to apply cash rounding when the minimum unit of account is smaller than the lowest physical\ndenomination of the currency.", "readOnly": true, "required": false }, { "name": "tenders", "type": "array", "description": "The tenders that were used to pay for the order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/Tender" }, { "name": "refunds", "type": "array", "description": "The refunds that are part of this order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/Refund" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp for when the order was created, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "closed_at", "type": "string", "description": "The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "state", "type": "#/components/schemas/OrderState", "description": "The current state of the order.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The version number, which is incremented each time an update is committed to the order.\nOrders not created through the API do not include a version number and\ntherefore cannot be updated.\n\n[Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders).", "readOnly": false, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_tip_money", "type": "#/components/schemas/Money", "description": "The total amount of tip money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of money collected in service charges for the order.\n\nNote: `total_service_charge_money` is the sum of `applied_money` fields for each individual\nservice charge. Therefore, `total_service_charge_money` only includes inclusive tax amounts,\nnot additive tax amounts.", "readOnly": true, "required": false }, { "name": "ticket_name", "type": "string", "description": "A short-term identifier for the order (such as a customer first name,\ntable number, or auto-generated order number that resets daily).", "readOnly": false, "required": false }, { "name": "pricing_options", "type": "#/components/schemas/OrderPricingOptions", "description": "Pricing options for an order. The options affect how the order's price is calculated.\nThey can be used, for example, to apply automatic price adjustments that are based on\npreconfigured [pricing rules](entity:CatalogPricingRule).", "readOnly": false, "required": false }, { "name": "rewards", "type": "array", "description": "A set-like list of Rewards that have been added to the Order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReward" }, { "name": "net_amount_due_money", "type": "#/components/schemas/Money", "description": "The net amount of money due on the order.", "readOnly": true, "required": false } ] }, { "name": "OrderSource", "properties": [ { "name": "name", "type": "string", "description": "The name used to identify the place (physical or digital) that an order originates.\nIf unset, the name defaults to the name of the application that created the order.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItem", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the line item only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the line item.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The count, or measurement, of a line item being purchased:\n\nIf `quantity` is a whole number, and `quantity_unit` is not specified, then `quantity` denotes an item count. For example: `3` apples.\n\nIf `quantity` is a whole or decimal number, and `quantity_unit` is also specified, then `quantity` denotes a measurement. For example: `2.25` pounds of broccoli.\n\nFor more information, see [Specify item quantity and measurement unit](https://developer.squareup.com/docs/orders-api/create-orders#specify-item-quantity-and-measurement-unit).\n\nLine items with a quantity of `0` are automatically removed\nwhen paying for or otherwise completing the order.", "readOnly": false, "required": true }, { "name": "quantity_unit", "type": "#/components/schemas/OrderQuantityUnit", "description": "The measurement unit and decimal precision that this line item's quantity is measured in.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "An optional note associated with the line item.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this line item.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item references.", "readOnly": false, "required": false }, { "name": "variation_name", "type": "string", "description": "The name of the variation applied to this line item.", "readOnly": false, "required": false }, { "name": "item_type", "type": "#/components/schemas/OrderLineItemItemType", "description": "The type of line item: an itemized sale, a non-itemized sale (custom amount), or the\nactivation or reloading of a gift card.\n", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this line item. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "modifiers", "type": "array", "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemModifier" }, { "name": "applied_taxes", "type": "array", "description": "The list of references to taxes applied to this line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a\ntop-level `OrderLineItemTax` applied to the line item. On reads, the\namount applied is populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every line\nitem for all `ORDER` scoped taxes added to the order. `OrderLineItemAppliedTax`\nrecords for `LINE_ITEM` scoped taxes must be added in requests for the tax\nto apply to any line items.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "applied_discounts", "type": "array", "description": "The list of references to discounts applied to this line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderLineItemDiscounts` applied to the line item. On reads, the amount\napplied is populated.\n\nAn `OrderLineItemAppliedDiscount` is automatically created on every line item for all\n`ORDER` scoped discounts that are added to the order. `OrderLineItemAppliedDiscount` records\nfor `LINE_ITEM` scoped discounts must be added in requests for the discount to apply to any\nline items.\n\nTo change the amount of a discount, modify the referenced top-level discount.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedDiscount" }, { "name": "applied_service_charges", "type": "array", "description": "The list of references to service charges applied to this line item. Each\n`OrderLineItemAppliedServiceCharge` has a `service_charge_id` that references the `uid` of a\ntop-level `OrderServiceCharge` applied to the line item. On reads, the amount applied is\npopulated.\n\nTo change the amount of a service charge, modify the referenced top-level service charge.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedServiceCharge" }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for a single unit of the line item.", "readOnly": false, "required": false }, { "name": "variation_total_price_money", "type": "#/components/schemas/Money", "description": "The total price of all item variations sold in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity`.\nIt does not include modifiers.", "readOnly": true, "required": false }, { "name": "gross_sales_money", "type": "#/components/schemas/Money", "description": "The amount of money made in gross sales for this line item.\nThe amount is calculated as the sum of the variation's total price and each modifier's total price.\nFor inclusive tax items in the US, Canada, and Japan, tax is deducted from `gross_sales_money`. For Europe and\nAustralia, inclusive tax remains as part of the gross sale calculation.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the line item.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to collect for the line item.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for this line item.", "readOnly": true, "required": false }, { "name": "pricing_blocklists", "type": "#/components/schemas/OrderLineItemPricingBlocklists", "description": "Describes pricing adjustments that are blocked from automatic\napplication to a line item. For more information, see\n[Apply Taxes and Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).", "readOnly": false, "required": false }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of apportioned service charge money to collect for the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderQuantityUnit", "properties": [ { "name": "measurement_unit", "type": "#/components/schemas/MeasurementUnit", "description": "A [MeasurementUnit](entity:MeasurementUnit) that represents the\nunit of measure for the quantity.", "readOnly": false, "required": false }, { "name": "precision", "type": "integer", "description": "For non-integer quantities, represents the number of digits after the decimal point that are\nrecorded for this quantity.\n\nFor example, a precision of 1 allows quantities such as `\"1.0\"` and `\"1.1\"`, but not `\"1.01\"`.\n\nMin: 0. Max: 5.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing the\n[CatalogMeasurementUnit](entity:CatalogMeasurementUnit).\n\nThis field is set when this is a catalog-backed measurement unit.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this measurement unit references.\n\nThis field is set when this is a catalog-backed measurement unit.", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnit", "properties": [ { "name": "custom_unit", "type": "#/components/schemas/MeasurementUnitCustom", "description": "A custom unit of measurement defined by the seller using the Point of Sale\napp or ad-hoc as an order line item.", "readOnly": false, "required": false }, { "name": "area_unit", "type": "#/components/schemas/MeasurementUnitArea", "description": "Represents a standard area unit.\n", "readOnly": false, "required": false }, { "name": "length_unit", "type": "#/components/schemas/MeasurementUnitLength", "description": "Represents a standard length unit.\n", "readOnly": false, "required": false }, { "name": "volume_unit", "type": "#/components/schemas/MeasurementUnitVolume", "description": "Represents a standard volume unit.\n", "readOnly": false, "required": false }, { "name": "weight_unit", "type": "#/components/schemas/MeasurementUnitWeight", "description": "Represents a standard unit of weight or mass.\n", "readOnly": false, "required": false }, { "name": "generic_unit", "type": "#/components/schemas/MeasurementUnitGeneric", "description": "Reserved for API integrations that lack the ability to specify a real measurement unit\n", "readOnly": false, "required": false }, { "name": "time_unit", "type": "#/components/schemas/MeasurementUnitTime", "description": "Represents a standard unit of time.\n", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/MeasurementUnitUnitType", "description": "Represents the type of the measurement unit.\n", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnitCustom", "properties": [ { "name": "name", "type": "string", "description": "The name of the custom unit, for example \"bushel\".", "readOnly": false, "required": true }, { "name": "abbreviation", "type": "string", "description": "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears\nin the cart for the Point of Sale app, and in reports.", "readOnly": false, "required": true } ] }, { "name": "MeasurementUnitArea", "properties": [] }, { "name": "MeasurementUnitLength", "properties": [] }, { "name": "MeasurementUnitVolume", "properties": [] }, { "name": "MeasurementUnitWeight", "properties": [] }, { "name": "MeasurementUnitGeneric", "properties": [] }, { "name": "MeasurementUnitTime", "properties": [] }, { "name": "MeasurementUnitUnitType", "properties": [] }, { "name": "OrderLineItemItemType", "properties": [] }, { "name": "OrderLineItemModifier", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the modifier only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this modifier references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the item modifier.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0.", "readOnly": false, "required": false }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` will\noverride the predefined [CatalogModifier](entity:CatalogModifier) price.", "readOnly": false, "required": false }, { "name": "total_price_money", "type": "#/components/schemas/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "OrderLineItemAppliedTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied tax only within this order.", "readOnly": false, "required": false }, { "name": "tax_uid", "type": "string", "description": "The `uid` of the tax for which this applied tax represents. It must reference\na tax present in the `order.taxes` field.\n\nThis field is immutable. To change which taxes apply to a line item, delete and add a new\n`OrderLineItemAppliedTax`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the tax to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemAppliedDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied discount only within this order.", "readOnly": false, "required": false }, { "name": "discount_uid", "type": "string", "description": "The `uid` of the discount that the applied discount represents. It must\nreference a discount present in the `order.discounts` field.\n\nThis field is immutable. To change which discounts apply to a line item,\nyou must delete the discount and re-add it as a new `OrderLineItemAppliedDiscount`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the discount to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemAppliedServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied service charge only within this order.", "readOnly": false, "required": false }, { "name": "service_charge_uid", "type": "string", "description": "The `uid` of the service charge that the applied service charge represents. It must\nreference a service charge present in the `order.service_charges` field.\n\nThis field is immutable. To change which service charges apply to a line item,\ndelete and add a new `OrderLineItemAppliedServiceCharge`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the service charge to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemPricingBlocklists", "properties": [ { "name": "blocked_discounts", "type": "array", "description": "A list of discounts blocked from applying to the line item.\nDiscounts can be blocked by the `discount_uid` (for ad hoc discounts) or\nthe `discount_catalog_object_id` (for catalog discounts).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemPricingBlocklistsBlockedDiscount" }, { "name": "blocked_taxes", "type": "array", "description": "A list of taxes blocked from applying to the line item.\nTaxes can be blocked by the `tax_uid` (for ad hoc taxes) or\nthe `tax_catalog_object_id` (for catalog taxes).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemPricingBlocklistsBlockedTax" } ] }, { "name": "OrderLineItemPricingBlocklistsBlockedDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID of the `BlockedDiscount` within the order.", "readOnly": false, "required": false }, { "name": "discount_uid", "type": "string", "description": "The `uid` of the discount that should be blocked. Use this field to block\nad hoc discounts. For catalog discounts, use the `discount_catalog_object_id` field.", "readOnly": false, "required": false }, { "name": "discount_catalog_object_id", "type": "string", "description": "The `catalog_object_id` of the discount that should be blocked.\nUse this field to block catalog discounts. For ad hoc discounts, use the\n`discount_uid` field.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItemPricingBlocklistsBlockedTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID of the `BlockedTax` within the order.", "readOnly": false, "required": false }, { "name": "tax_uid", "type": "string", "description": "The `uid` of the tax that should be blocked. Use this field to block\nad hoc taxes. For catalog, taxes use the `tax_catalog_object_id` field.", "readOnly": false, "required": false }, { "name": "tax_catalog_object_id", "type": "string", "description": "The `catalog_object_id` of the tax that should be blocked.\nUse this field to block catalog taxes. For ad hoc taxes, use the\n`tax_uid` field.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItemTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the tax only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this tax references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The tax's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal\nnumber. For example, a value of `\"7.25\"` corresponds to a percentage of\n7.25%.", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this tax. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the tax.\n\n- For percentage-based taxes, `applied_money` is the money\ncalculated using the percentage.", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemTaxScope", "description": "Indicates the level at which the tax applies. For `ORDER` scoped taxes,\nSquare generates references in `applied_taxes` on all order line items that do\nnot have them. For `LINE_ITEM` scoped taxes, the tax only applies to line items\nwith references in their `applied_taxes` field.\n\nThis field is immutable. To change the scope, you must delete the tax and\nre-add it as a new tax.\n", "readOnly": false, "required": false }, { "name": "auto_applied", "type": "boolean", "description": "Determines whether the tax was automatically applied to the order based on\nthe catalog configuration. For an example, see\n[Automatically Apply Taxes to an Order](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes).", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemTaxType", "properties": [] }, { "name": "OrderLineItemTaxScope", "properties": [] }, { "name": "OrderLineItemDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the discount only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this discount references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The discount's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemDiscountType", "description": "The type of the discount.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the discount, as a string representation of a decimal number.\nA value of `7.25` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of discount actually applied to the line item.\n\nThe amount represents the amount of money applied as a line-item scoped discount.\nWhen an amount-based discount is scoped to the entire order, the value\nof `applied_money` is different than `amount_money` because the total\namount of the discount is distributed across all line items.", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this discount. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemDiscountScope", "description": "Indicates the level at which the discount applies. For `ORDER` scoped discounts,\nSquare generates references in `applied_discounts` on all order line items that do\nnot have them. For `LINE_ITEM` scoped discounts, the discount only applies to line items\nwith a discount reference in their `applied_discounts` field.\n\nThis field is immutable. To change the scope of a discount, you must delete\nthe discount and re-add it as a new discount.\n", "readOnly": false, "required": false }, { "name": "reward_ids", "type": "array", "description": "The reward IDs corresponding to this discount. The application and\nspecification of discounts that have `reward_ids` are completely controlled by the backing\ncriteria corresponding to the reward tiers of the rewards that are added to the order\nthrough the Loyalty API. To manually unapply discounts that are the result of added rewards,\nthe rewards must be removed from the order through the Loyalty API.", "readOnly": true, "required": false }, { "name": "pricing_rule_id", "type": "string", "description": "The object ID of a [pricing rule](entity:CatalogPricingRule) to be applied\nautomatically to this discount. The specification and application of the discounts, to\nwhich a `pricing_rule_id` is assigned, are completely controlled by the corresponding\npricing rule.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemDiscountType", "properties": [] }, { "name": "OrderLineItemDiscountScope", "properties": [] }, { "name": "OrderServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the service charge only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the service charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing the service charge [CatalogObject](entity:CatalogObject).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this service charge references.", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The service charge percentage as a string representation of a\ndecimal number. For example, `\"7.25\"` indicates a service charge of 7.25%.\n\nExactly 1 of `percentage` or `amount_money` should be set.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of a non-percentage-based service charge.\n\nExactly one of `percentage` or `amount_money` should be set.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the service charge,\nincluding any inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money\ncalculated using the percentage.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the service charge.\n\n__Note__: If an inclusive tax is applied to the service charge,\n`total_money` does not equal `applied_money` plus `total_tax_money`\nbecause the inclusive tax amount is already included in both\n`applied_money` and `total_tax_money`.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/OrderServiceChargeCalculationPhase", "description": "The calculation phase at which to apply the service charge.\n", "readOnly": false, "required": false }, { "name": "taxable", "type": "boolean", "description": "Indicates whether the service charge can be taxed. If set to `true`,\norder-level taxes automatically apply to the service charge. Note that\nservice charges calculated in the `TOTAL_PHASE` cannot be marked as taxable.", "readOnly": false, "required": false }, { "name": "applied_taxes", "type": "array", "description": "The list of references to the taxes applied to this service charge. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderLineItemTax` that is being applied to this service charge. On reads, the amount applied\nis populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every taxable service charge\nfor all `ORDER` scoped taxes that are added to the order. `OrderLineItemAppliedTax` records\nfor `LINE_ITEM` scoped taxes must be added in requests for the tax to apply to any taxable\nservice charge. Taxable service charges have the `taxable` field set to `true` and calculated\nin the `SUBTOTAL_PHASE`.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this service charge. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderServiceChargeType", "description": "The type of the service charge.\n", "readOnly": true, "required": false }, { "name": "treatment_type", "type": "#/components/schemas/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\n", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\n", "readOnly": false, "required": false } ] }, { "name": "OrderServiceChargeCalculationPhase", "properties": [] }, { "name": "OrderServiceChargeType", "properties": [] }, { "name": "OrderServiceChargeTreatmentType", "properties": [] }, { "name": "OrderServiceChargeScope", "properties": [] }, { "name": "Fulfillment", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the fulfillment only within this order.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/FulfillmentType", "description": "The type of the fulfillment.\n", "readOnly": false, "required": false }, { "name": "state", "type": "#/components/schemas/FulfillmentState", "description": "The state of the fulfillment.\n", "readOnly": false, "required": false }, { "name": "line_item_application", "type": "#/components/schemas/FulfillmentFulfillmentLineItemApplication", "description": "Describes what order line items this fulfillment applies to.\nIt can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.\n", "readOnly": true, "required": false }, { "name": "entries", "type": "array", "description": "A list of entries pertaining to the fulfillment of an order. Each entry must reference\na valid `uid` for an order line item in the `line_item_uid` field, as well as a `quantity` to\nfulfill.\n\nMultiple entries can reference the same line item `uid`, as long as the total quantity among\nall fulfillment entries referencing a single line item does not exceed the quantity of the\norder's line item itself.\n\nAn order cannot be marked as `COMPLETED` before all fulfillments are `COMPLETED`,\n`CANCELED`, or `FAILED`. Fulfillments can be created and completed independently\nbefore order completion.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/FulfillmentFulfillmentEntry" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this fulfillment. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "pickup_details", "type": "#/components/schemas/FulfillmentPickupDetails", "description": "Contains details for a pickup fulfillment. These details are required when the fulfillment\ntype is `PICKUP`.", "readOnly": false, "required": false }, { "name": "shipment_details", "type": "#/components/schemas/FulfillmentShipmentDetails", "description": "Contains details for a shipment fulfillment. These details are required when the fulfillment type\nis `SHIPMENT`.\n\nA shipment fulfillment's relationship to fulfillment `state`:\n`PROPOSED`: A shipment is requested.\n`RESERVED`: Fulfillment in progress. Shipment processing.\n`PREPARED`: Shipment packaged. Shipping label created.\n`COMPLETED`: Package has been shipped.\n`CANCELED`: Shipment has been canceled.\n`FAILED`: Shipment has failed.", "readOnly": false, "required": false }, { "name": "delivery_details", "type": "#/components/schemas/FulfillmentDeliveryDetails", "description": "Describes delivery details of an order fulfillment.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentType", "properties": [] }, { "name": "FulfillmentState", "properties": [] }, { "name": "FulfillmentFulfillmentLineItemApplication", "properties": [] }, { "name": "FulfillmentFulfillmentEntry", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the fulfillment entry only within this order.", "readOnly": false, "required": false }, { "name": "line_item_uid", "type": "string", "description": "The `uid` from the order line item.", "readOnly": false, "required": true }, { "name": "quantity", "type": "string", "description": "The quantity of the line item being fulfilled, formatted as a decimal number.\nFor example, `\"3\"`.\n\nFulfillments for line items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "readOnly": false, "required": true }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this fulfillment entry. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false } ] }, { "name": "FulfillmentPickupDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "Information about the person to pick up this fulfillment from a physical\nlocation.", "readOnly": false, "required": false }, { "name": "expires_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment expires if it is not marked in progress. The timestamp must be\nin RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\"). The expiration time can only be set\nup to 7 days in the future. If `expires_at` is not set, any new payments attached to the order\nare automatically completed.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "auto_complete_duration", "type": "string", "description": "The duration of time after which an in progress pickup fulfillment is automatically moved\nto the `COMPLETED` state. The duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nIf not set, this pickup fulfillment remains in progress until it is canceled or completed.\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "schedule_type", "type": "#/components/schemas/FulfillmentPickupDetailsScheduleType", "description": "The schedule type of the pickup fulfillment. Defaults to `SCHEDULED`.\n", "readOnly": false, "required": false }, { "name": "pickup_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the pickup window. Must be in RFC 3339 timestamp format, e.g.,\n\"2016-09-04T23:59:33.123Z\".\n\nFor fulfillments with the schedule type `ASAP`, this is automatically set\nto the current time plus the expected duration to prepare the fulfillment.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "pickup_window_duration", "type": "string", "description": "The window of time in which the order should be picked up after the `pickup_at` timestamp.\nMust be in RFC 3339 duration format, e.g., \"P1W3D\". Can be used as an\ninformational guideline for merchants.\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "prep_time_duration", "type": "string", "description": "The duration of time it takes to prepare this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "A note to provide additional instructions about the pickup\nfulfillment displayed in the Square Point of Sale application and set by the API.", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "accepted_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was marked in progress. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "rejected_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "ready_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment is marked as ready for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "expired_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment expired. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "picked_up_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was picked up by the recipient. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "string", "description": "A description of why the pickup was canceled. The maximum length: 100 characters.", "readOnly": false, "required": false }, { "name": "is_curbside_pickup", "type": "boolean", "description": "If set to `true`, indicates that this pickup order is for curbside pickup, not in-store pickup.", "readOnly": false, "required": false }, { "name": "curbside_pickup_details", "type": "#/components/schemas/FulfillmentPickupDetailsCurbsidePickupDetails", "description": "Specific details for curbside pickup. These details can only be populated if `is_curbside_pickup` is set to `true`.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentRecipient", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer associated with the fulfillment.\n\nIf `customer_id` is provided, the fulfillment recipient's `display_name`,\n`email_address`, and `phone_number` are automatically populated from the\ntargeted customer profile. If these fields are set in the request, the request\nvalues override the information from the customer profile. If the\ntargeted customer profile does not contain the necessary information and\nthese fields are left unset, the request results in an error.", "readOnly": false, "required": false }, { "name": "display_name", "type": "string", "description": "The display name of the fulfillment recipient. This field is required.\n\nIf provided, the display name overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "email_address", "type": "string", "description": "The email address of the fulfillment recipient.\n\nIf provided, the email address overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number of the fulfillment recipient. This field is required.\n\nIf provided, the phone number overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The address of the fulfillment recipient. This field is required.\n\nIf provided, the address overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "FulfillmentPickupDetailsScheduleType", "properties": [] }, { "name": "FulfillmentPickupDetailsCurbsidePickupDetails", "properties": [ { "name": "curbside_details", "type": "string", "description": "Specific details for curbside pickup, such as parking number and vehicle model.", "readOnly": false, "required": false }, { "name": "buyer_arrived_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the buyer arrived and is waiting for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false } ] }, { "name": "FulfillmentShipmentDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "Information about the person to receive this shipment fulfillment.", "readOnly": false, "required": false }, { "name": "carrier", "type": "string", "description": "The shipping carrier being used to ship this fulfillment (such as UPS, FedEx, or USPS).", "readOnly": false, "required": false }, { "name": "shipping_note", "type": "string", "description": "A note with additional information for the shipping carrier.", "readOnly": false, "required": false }, { "name": "shipping_type", "type": "string", "description": "A description of the type of shipping product purchased from the carrier\n(such as First Class, Priority, or Express).", "readOnly": false, "required": false }, { "name": "tracking_number", "type": "string", "description": "The reference number provided by the carrier to track the shipment's progress.", "readOnly": false, "required": false }, { "name": "tracking_url", "type": "string", "description": "A link to the tracking webpage on the carrier's website.", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment was requested. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "in_progress_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `RESERVED` state, which indicates that preparation\nof this shipment has begun. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "packaged_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `PREPARED` state, which indicates that the\nfulfillment is packaged. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "expected_shipped_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment is expected to be delivered to the shipping carrier.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "shipped_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `COMPLETED` state, which indicates that\nthe fulfillment has been given to the shipping carrier. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating the shipment was canceled.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "cancel_reason", "type": "string", "description": "A description of why the shipment was canceled.", "readOnly": false, "required": false }, { "name": "failed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment failed to be completed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "failure_reason", "type": "string", "description": "A description of why the shipment failed to be completed.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentDeliveryDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "The contact information for the person to receive the fulfillment.", "readOnly": false, "required": false }, { "name": "schedule_type", "type": "#/components/schemas/FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType", "description": "Indicates the fulfillment delivery schedule type. If `SCHEDULED`, then\n`deliver_at` is required. If `ASAP`, then `prep_time_duration` is required. The default is `SCHEDULED`.\n", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nMust be in RFC 3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "deliver_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the delivery period.\nWhen the fulfillment `schedule_type` is `ASAP`, the field is automatically\nset to the current time plus the `prep_time_duration`.\nOtherwise, the application can set this field while the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the\nterminal state such as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "prep_time_duration", "type": "string", "description": "The duration of time it takes to prepare and deliver this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "delivery_window_duration", "type": "string", "description": "The time period after `deliver_at` in which to deliver the order.\nApplications can set this field when the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the terminal state\nsuch as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "Provides additional instructions about the delivery fulfillment.\nIt is displayed in the Square Point of Sale application and set by the API.", "readOnly": false, "required": false }, { "name": "completed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller completed the fulfillment.\nThis field is automatically set when fulfillment `state` changes to `COMPLETED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "in_progress_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller started processing the fulfillment.\nThis field is automatically set when the fulfillment `state` changes to `RESERVED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "rejected_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. This field is\nautomatically set when the fulfillment `state` changes to `FAILED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "ready_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the seller marked the fulfillment as ready for\ncourier pickup. This field is automatically set when the fulfillment `state` changes\nto PREPARED.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "delivered_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was delivered to the recipient.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. This field is automatically\nset when the fulfillment `state` changes to `CANCELED`.\n\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "string", "description": "The delivery cancellation reason. Max length: 100 characters.", "readOnly": false, "required": false }, { "name": "courier_pickup_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when an order can be picked up by the courier for delivery.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "courier_pickup_window_duration", "type": "string", "description": "The time period after `courier_pickup_at` in which the courier should pick up the order.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "is_no_contact_delivery", "type": "boolean", "description": "Whether the delivery is preferred to be no contact.", "readOnly": false, "required": false }, { "name": "dropoff_notes", "type": "string", "description": "A note to provide additional instructions about how to deliver the order.", "readOnly": false, "required": false }, { "name": "courier_provider_name", "type": "string", "description": "The name of the courier provider.", "readOnly": false, "required": false }, { "name": "courier_support_phone_number", "type": "string", "description": "The support phone number of the courier.", "readOnly": false, "required": false }, { "name": "square_delivery_id", "type": "string", "description": "The identifier for the delivery created by Square.", "readOnly": false, "required": false }, { "name": "external_delivery_id", "type": "string", "description": "The identifier for the delivery created by the third-party courier service.", "readOnly": false, "required": false }, { "name": "managed_delivery", "type": "boolean", "description": "The flag to indicate the delivery is managed by a third party (ie DoorDash), which means\nwe may not receive all recipient information for PII purposes.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType", "properties": [] }, { "name": "OrderReturn", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return only within this order.", "readOnly": false, "required": false }, { "name": "source_order_id", "type": "string", "description": "An order that contains the original sale of these return line items. This is unset\nfor unlinked returns.", "readOnly": false, "required": false }, { "name": "return_line_items", "type": "array", "description": "A collection of line items that are being returned.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnLineItem" }, { "name": "return_service_charges", "type": "array", "description": "A collection of service charges that are being returned.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnServiceCharge" }, { "name": "return_taxes", "type": "array", "description": "A collection of references to taxes being returned for an order, including the total\napplied tax amount to be returned. The taxes must reference a top-level tax ID from the source\norder.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturnTax" }, { "name": "return_discounts", "type": "array", "description": "A collection of references to discounts being returned for an order, including the total\napplied discount amount to be returned. The discounts must reference a top-level discount ID\nfrom the source order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturnDiscount" }, { "name": "return_tips", "type": "array", "description": "A collection of references to tips being returned for an order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnTip" }, { "name": "rounding_adjustment", "type": "#/components/schemas/OrderRoundingAdjustment", "description": "A positive or negative rounding adjustment to the total value being returned. Adjustments are commonly\nused to apply cash rounding when the minimum unit of the account is smaller than the lowest\nphysical denomination of the currency.", "readOnly": false, "required": false }, { "name": "return_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "An aggregate monetary value being returned by this return entry.", "readOnly": false, "required": false } ] }, { "name": "OrderReturnLineItem", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID for this return line-item entry.", "readOnly": false, "required": false }, { "name": "source_line_item_uid", "type": "string", "description": "The `uid` of the line item in the original sale order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the line item.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity returned, formatted as a decimal number.\nFor example, `\"3\"`.\n\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "readOnly": false, "required": true }, { "name": "quantity_unit", "type": "#/components/schemas/OrderQuantityUnit", "description": "The unit and precision that this return line item's quantity is measured in.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "The note of the return line item.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this return line item.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item references.", "readOnly": false, "required": false }, { "name": "variation_name", "type": "string", "description": "The name of the variation applied to this return line item.", "readOnly": false, "required": false }, { "name": "item_type", "type": "#/components/schemas/OrderLineItemItemType", "description": "The type of line item: an itemized return, a non-itemized return (custom amount),\nor the return of an unactivated gift card sale.\n", "readOnly": false, "required": false }, { "name": "return_modifiers", "type": "array", "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnLineItemModifier" }, { "name": "applied_taxes", "type": "array", "description": "The list of references to `OrderReturnTax` entities applied to the return line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderReturnTax` applied to the return line item. On reads, the applied amount\nis populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "applied_discounts", "type": "array", "description": "The list of references to `OrderReturnDiscount` entities applied to the return line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderReturnDiscount` applied to the return line item. On reads, the applied amount\nis populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedDiscount" }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for a single unit of the line item.", "readOnly": false, "required": false }, { "name": "variation_total_price_money", "type": "#/components/schemas/Money", "description": "The total price of all item variations returned in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity` and\ndoes not include modifiers.", "readOnly": true, "required": false }, { "name": "gross_return_money", "type": "#/components/schemas/Money", "description": "The gross return amount of money calculated as (item base price + modifiers price) * quantity.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to return for the line item.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to return for the line item.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to return for this line item.", "readOnly": true, "required": false }, { "name": "applied_service_charges", "type": "array", "description": "The list of references to `OrderReturnServiceCharge` entities applied to the return\nline item. Each `OrderLineItemAppliedServiceCharge` has a `service_charge_uid` that\nreferences the `uid` of a top-level `OrderReturnServiceCharge` applied to the return line\nitem. On reads, the applied amount is populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedServiceCharge" }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of apportioned service charge money to return for the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderReturnLineItemModifier", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return modifier only within this order.", "readOnly": false, "required": false }, { "name": "source_modifier_uid", "type": "string", "description": "The modifier `uid` from the order's line item that contains the\noriginal sale of this line item modifier.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item modifier references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the item modifier.", "readOnly": false, "required": false }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` overrides the predefined [CatalogModifier](entity:CatalogModifier) price.", "readOnly": false, "required": false }, { "name": "total_price_money", "type": "#/components/schemas/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0.", "readOnly": false, "required": false } ] }, { "name": "OrderReturnServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return service charge only within this order.", "readOnly": false, "required": false }, { "name": "source_service_charge_uid", "type": "string", "description": "The service charge `uid` from the order containing the original\nservice charge. `source_service_charge_uid` is `null` for\nunlinked returns.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the service charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID of the associated [OrderServiceCharge](entity:OrderServiceCharge).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this service charge references.", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "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%.\n\nEither `percentage` or `amount_money` should be set, but not both.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of a non-percentage-based service charge.\n\nEither `percentage` or `amount_money` should be set, but not both.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the service charge, including\nany inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money calculated using the percentage.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the service charge.\n\n__NOTE__: If an inclusive tax is applied to the service charge, `total_money`\ndoes not equal `applied_money` plus `total_tax_money` because the inclusive\ntax amount is already included in both `applied_money` and `total_tax_money`.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/OrderServiceChargeCalculationPhase", "description": "The calculation phase after which to apply the service charge.\n", "readOnly": true, "required": false }, { "name": "taxable", "type": "boolean", "description": "Indicates whether the surcharge can be taxed. Service charges\ncalculated in the `TOTAL_PHASE` cannot be marked as taxable.", "readOnly": false, "required": false }, { "name": "applied_taxes", "type": "array", "description": "The list of references to `OrderReturnTax` entities applied to the\n`OrderReturnServiceCharge`. Each `OrderLineItemAppliedTax` has a `tax_uid`\nthat references the `uid` of a top-level `OrderReturnTax` that is being\napplied to the `OrderReturnServiceCharge`. On reads, the applied amount is\npopulated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "treatment_type", "type": "#/components/schemas/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\n", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the returned tax only within this order.", "readOnly": false, "required": false }, { "name": "source_tax_uid", "type": "string", "description": "The tax `uid` from the order that contains the original tax charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this tax references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The tax's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal number.\nFor example, a value of `\"7.25\"` corresponds to a percentage of 7.25%.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the tax in an order.", "readOnly": true, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemTaxScope", "description": "Indicates the level at which the `OrderReturnTax` applies. For `ORDER` scoped\ntaxes, Square generates references in `applied_taxes` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the returned discount only within this order.", "readOnly": false, "required": false }, { "name": "source_discount_uid", "type": "string", "description": "The discount `uid` from the order that contains the original application of this discount.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this discount references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The discount's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemDiscountType", "description": "The type of the discount. If it is created by the API, it is `FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal number.\nA value of `\"7.25\"` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of discount actually applied to this line item. When an amount-based\ndiscount is at the order level, this value is different from `amount_money` because the discount\nis distributed across the line items.", "readOnly": true, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemDiscountScope", "description": "Indicates the level at which the `OrderReturnDiscount` applies. For `ORDER` scoped\ndiscounts, the server generates references in `applied_discounts` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the discount is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnTip", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the tip only within this order.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of tip being returned\n--", "readOnly": true, "required": false }, { "name": "source_tender_uid", "type": "string", "description": "The tender `uid` from the order that contains the original application of this tip.", "readOnly": false, "required": false }, { "name": "source_tender_id", "type": "string", "description": "The tender `id` from the order that contains the original application of this tip.", "readOnly": false, "required": false } ] }, { "name": "OrderRoundingAdjustment", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the rounding adjustment only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the rounding adjustment from the original sale order.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The actual rounding adjustment amount.", "readOnly": false, "required": false } ] }, { "name": "OrderMoneyAmounts", "properties": [ { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total money.", "readOnly": false, "required": false }, { "name": "tax_money", "type": "#/components/schemas/Money", "description": "The money associated with taxes.", "readOnly": false, "required": false }, { "name": "discount_money", "type": "#/components/schemas/Money", "description": "The money associated with discounts.", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The money associated with tips.", "readOnly": false, "required": false }, { "name": "service_charge_money", "type": "#/components/schemas/Money", "description": "The money associated with service charges.", "readOnly": false, "required": false } ] }, { "name": "Tender", "properties": [ { "name": "id", "type": "string", "description": "The tender's unique ID. It is the associated payment ID.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the transaction's associated location.", "readOnly": false, "required": false }, { "name": "transaction_id", "type": "string", "description": "The ID of the tender's associated transaction.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp for when the tender was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "note", "type": "string", "description": "An optional note associated with the tender at the time of payment.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total amount of the tender, including `tip_money`. If the tender has a `payment_id`,\nthe `total_money` of the corresponding [Payment](entity:Payment) will be equal to the\n`amount_money` of the tender.", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The tip's amount of the tender.", "readOnly": false, "required": false }, { "name": "processing_fee_money", "type": "#/components/schemas/Money", "description": "The amount of any Square processing fees applied to the tender.\n\nThis field is not immediately populated when a new transaction is created.\nIt is usually available after about ten seconds.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "If the tender is associated with a customer or represents a customer's card on file,\nthis is the ID of the associated customer.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/TenderType", "description": "The type of tender, such as `CARD` or `CASH`.\n", "readOnly": false, "required": true }, { "name": "card_details", "type": "#/components/schemas/TenderCardDetails", "description": "The details of the card tender.\n\nThis value is present only if the value of `type` is `CARD`.", "readOnly": false, "required": false }, { "name": "cash_details", "type": "#/components/schemas/TenderCashDetails", "description": "The details of the cash tender.\n\nThis value is present only if the value of `type` is `CASH`.", "readOnly": false, "required": false }, { "name": "bank_account_details", "type": "#/components/schemas/TenderBankAccountDetails", "description": "The details of the bank account tender.\n\nThis value is present only if the value of `type` is `BANK_ACCOUNT`.", "readOnly": false, "required": false }, { "name": "buy_now_pay_later_details", "type": "#/components/schemas/TenderBuyNowPayLaterDetails", "description": "The details of a Buy Now Pay Later tender.\n\nThis value is present only if the value of `type` is `BUY_NOW_PAY_LATER`.", "readOnly": false, "required": false }, { "name": "square_account_details", "type": "#/components/schemas/TenderSquareAccountDetails", "description": "The details of a Square Account tender.\n\nThis value is present only if the value of `type` is `SQUARE_ACCOUNT`.", "readOnly": false, "required": false }, { "name": "additional_recipients", "type": "array", "description": "Additional recipients (other than the merchant) receiving a portion of this tender.\nFor example, fees assessed on the purchase by a third party integration.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/AdditionalRecipient" }, { "name": "payment_id", "type": "string", "description": "The ID of the [Payment](entity:Payment) that corresponds to this tender.\nThis value is only present for payments created with the v2 Payments API.", "readOnly": false, "required": false } ] }, { "name": "TenderType", "properties": [] }, { "name": "TenderCardDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderCardDetailsStatus", "description": "The credit card payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderCardDetailsStatus](entity:TenderCardDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false }, { "name": "card", "type": "#/components/schemas/Card", "description": "The credit card's non-confidential details.", "readOnly": false, "required": false }, { "name": "entry_method", "type": "#/components/schemas/TenderCardDetailsEntryMethod", "description": "The method used to enter the card's details for the transaction.\n", "readOnly": false, "required": false } ] }, { "name": "TenderCardDetailsStatus", "properties": [] }, { "name": "Card", "properties": [ { "name": "id", "type": "string", "description": "Unique ID for this card. Generated by Square.", "readOnly": true, "required": false }, { "name": "card_brand", "type": "#/components/schemas/CardBrand", "description": "The card's brand.\n", "readOnly": true, "required": false }, { "name": "last_4", "type": "string", "description": "The last 4 digits of the card number.", "readOnly": true, "required": false }, { "name": "exp_month", "type": "integer", "description": "The expiration month of the associated card as an integer between 1 and 12.", "readOnly": false, "required": false }, { "name": "exp_year", "type": "integer", "description": "The four-digit year of the card's expiration date.", "readOnly": false, "required": false }, { "name": "cardholder_name", "type": "string", "description": "The name of the cardholder.", "readOnly": false, "required": false }, { "name": "billing_address", "type": "#/components/schemas/Address", "description": "The billing address for this card.", "readOnly": false, "required": false }, { "name": "fingerprint", "type": "string", "description": "Intended as a Square-assigned identifier, based\non the card number, to identify the card across multiple locations within a\nsingle application.", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "**Required** The ID of a customer created using the Customers API to be associated with the card.", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the merchant associated with the card.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional user-defined reference ID that associates this card with\nanother entity in an external system. For example, a customer ID from an\nexternal customer management system.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "Indicates whether or not a card can be used for payments.", "readOnly": true, "required": false }, { "name": "card_type", "type": "#/components/schemas/CardType", "description": "The type of the card.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "prepaid_type", "type": "#/components/schemas/CardPrepaidType", "description": "Indicates whether the Card is prepaid or not.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "bin", "type": "string", "description": "The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API\nreturns this field.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "Current version number of the card. Increments with each card update. Requests to update an\nexisting Card object will be rejected unless the version in the request matches the current\nversion for the Card.", "readOnly": false, "required": false }, { "name": "card_co_brand", "type": "#/components/schemas/CardCoBrand", "description": "The card's co-brand if available. For example, an Afterpay virtual card would have a\nco-brand of AFTERPAY.\n", "readOnly": true, "required": false } ] }, { "name": "CardBrand", "properties": [] }, { "name": "CardType", "properties": [] }, { "name": "CardPrepaidType", "properties": [] }, { "name": "CardCoBrand", "properties": [] }, { "name": "TenderCardDetailsEntryMethod", "properties": [] }, { "name": "TenderCashDetails", "properties": [ { "name": "buyer_tendered_money", "type": "#/components/schemas/Money", "description": "The total amount of cash provided by the buyer, before change is given.", "readOnly": false, "required": false }, { "name": "change_back_money", "type": "#/components/schemas/Money", "description": "The amount of change returned to the buyer.", "readOnly": false, "required": false } ] }, { "name": "TenderBankAccountDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderBankAccountDetailsStatus", "description": "The bank account payment's current state.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "TenderBankAccountDetailsStatus", "properties": [] }, { "name": "TenderBuyNowPayLaterDetails", "properties": [ { "name": "buy_now_pay_later_brand", "type": "#/components/schemas/TenderBuyNowPayLaterDetailsBrand", "description": "The Buy Now Pay Later brand.\n", "readOnly": true, "required": false }, { "name": "status", "type": "#/components/schemas/TenderBuyNowPayLaterDetailsStatus", "description": "The buy now pay later payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderBuyNowPayLaterDetailsStatus](entity:TenderBuyNowPayLaterDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false } ] }, { "name": "TenderBuyNowPayLaterDetailsBrand", "properties": [] }, { "name": "TenderBuyNowPayLaterDetailsStatus", "properties": [] }, { "name": "TenderSquareAccountDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderSquareAccountDetailsStatus", "description": "The Square Account payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderSquareAccountDetailsStatus](entity:TenderSquareAccountDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false } ] }, { "name": "TenderSquareAccountDetailsStatus", "properties": [] }, { "name": "AdditionalRecipient", "properties": [ { "name": "location_id", "type": "string", "description": "The location ID for a recipient (other than the merchant) receiving a portion of this tender.", "readOnly": false, "required": true }, { "name": "description", "type": "string", "description": "The description of the additional recipient.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money distributed to the recipient.", "readOnly": false, "required": true }, { "name": "receivable_id", "type": "string", "description": "The unique ID for the RETIRED `AdditionalRecipientReceivable` object. This field should be empty for any `AdditionalRecipient` objects created after the retirement.", "readOnly": false, "required": false } ] }, { "name": "Refund", "properties": [ { "name": "id", "type": "string", "description": "The refund's unique ID.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The ID of the refund's associated location.", "readOnly": false, "required": true }, { "name": "transaction_id", "type": "string", "description": "The ID of the transaction that the refunded tender is part of.", "readOnly": false, "required": false }, { "name": "tender_id", "type": "string", "description": "The ID of the refunded tender.", "readOnly": false, "required": true }, { "name": "created_at", "type": "string", "description": "The timestamp for when the refund was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "reason", "type": "string", "description": "The reason for the refund being issued.", "readOnly": false, "required": true }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money refunded to the buyer.", "readOnly": false, "required": true }, { "name": "status", "type": "#/components/schemas/RefundStatus", "description": "The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`,\nor `FAILED`).\n", "readOnly": false, "required": true }, { "name": "processing_fee_money", "type": "#/components/schemas/Money", "description": "The amount of Square processing fee money refunded to the *merchant*.", "readOnly": false, "required": false }, { "name": "additional_recipients", "type": "array", "description": "Additional recipients (other than the merchant) receiving a portion of this refund.\nFor example, fees assessed on a refund of a purchase by a third party integration.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/AdditionalRecipient" } ] }, { "name": "RefundStatus", "properties": [] }, { "name": "OrderState", "properties": [] }, { "name": "OrderPricingOptions", "properties": [ { "name": "auto_apply_discounts", "type": "boolean", "description": "The option to determine whether pricing rule-based\ndiscounts are automatically applied to an order.", "readOnly": false, "required": false }, { "name": "auto_apply_taxes", "type": "boolean", "description": "The option to determine whether rule-based taxes are automatically\napplied to an order when the criteria of the corresponding rules are met.", "readOnly": false, "required": false } ] }, { "name": "OrderReward", "properties": [ { "name": "id", "type": "string", "description": "The identifier of the reward.", "readOnly": false, "required": true }, { "name": "reward_tier_id", "type": "string", "description": "The identifier of the reward tier corresponding to this reward.", "readOnly": false, "required": true } ] } ], "CloneOrderRequest": [ { "name": "CloneOrderRequest", "properties": [ { "name": "order_id", "type": "string", "description": "The ID of the order to clone.", "readOnly": false, "required": true }, { "name": "version", "type": "integer", "description": "An optional order version for concurrency protection.\n\nIf a version is provided, it must match the latest stored version of the order to clone.\nIf a version is not provided, the API clones the latest version.", "readOnly": false, "required": false }, { "name": "idempotency_key", "type": "string", "description": "A value you specify that uniquely identifies this clone request.\n\nIf you are unsure whether a particular order was cloned successfully,\nyou can reattempt the call with the same idempotency key without\nworrying about creating duplicate cloned orders.\nThe originally cloned order is returned.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false } ] } ], "SearchOrdersRequest": [ { "name": "SearchOrdersRequest", "properties": [ { "name": "location_ids", "type": "array", "description": "The location IDs for the orders to query. All locations must belong to\nthe same merchant.\n\nMax: 10 location IDs.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for your original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "query", "type": "#/components/schemas/SearchOrdersQuery", "description": "Query conditions used to filter or sort the results. Note that when\nretrieving additional pages using a cursor, you must use the original query.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to be returned in a single page.\n\nDefault: `500`\nMax: `1000`", "readOnly": false, "required": false }, { "name": "return_entries", "type": "boolean", "description": "A Boolean that controls the format of the search results. If `true`,\n`SearchOrders` returns [OrderEntry](entity:OrderEntry) objects. If `false`, `SearchOrders`\nreturns complete order objects.\n\nDefault: `false`.", "readOnly": false, "required": false } ] }, { "name": "SearchOrdersQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/SearchOrdersFilter", "description": "Criteria to filter results by.", "readOnly": false, "required": false }, { "name": "sort", "type": "#/components/schemas/SearchOrdersSort", "description": "Criteria to sort results by.", "readOnly": false, "required": false } ] }, { "name": "SearchOrdersFilter", "properties": [ { "name": "state_filter", "type": "#/components/schemas/SearchOrdersStateFilter", "description": "Filter by [OrderState](entity:OrderState).", "readOnly": false, "required": false }, { "name": "date_time_filter", "type": "#/components/schemas/SearchOrdersDateTimeFilter", "description": "Filter for results within a time range.\n\n__Important:__ If you filter for orders by time range, you must set `SearchOrdersSort`\nto sort by the same field.\n[Learn more about filtering orders by time range.](https://developer.squareup.com/docs/orders-api/manage-orders/search-orders#important-note-about-filtering-orders-by-time-range)", "readOnly": false, "required": false }, { "name": "fulfillment_filter", "type": "#/components/schemas/SearchOrdersFulfillmentFilter", "description": "Filter by the fulfillment type or state.", "readOnly": false, "required": false }, { "name": "source_filter", "type": "#/components/schemas/SearchOrdersSourceFilter", "description": "Filter by the source of the order.", "readOnly": false, "required": false }, { "name": "customer_filter", "type": "#/components/schemas/SearchOrdersCustomerFilter", "description": "Filter by customers associated with the order.", "readOnly": false, "required": false } ] }, { "name": "SearchOrdersStateFilter", "properties": [ { "name": "states", "type": "array", "description": "States to filter for.\n", "readOnly": false, "required": true, "arrayType": "#/components/schemas/OrderState" } ] }, { "name": "OrderState", "properties": [] }, { "name": "SearchOrdersDateTimeFilter", "properties": [ { "name": "created_at", "type": "#/components/schemas/TimeRange", "description": "The time range for filtering on the `created_at` timestamp. If you use this\nvalue, you must set the `sort_field` in the `OrdersSearchSort` object to\n`CREATED_AT`.", "readOnly": false, "required": false }, { "name": "updated_at", "type": "#/components/schemas/TimeRange", "description": "The time range for filtering on the `updated_at` timestamp. If you use this\nvalue, you must set the `sort_field` in the `OrdersSearchSort` object to\n`UPDATED_AT`.", "readOnly": false, "required": false }, { "name": "closed_at", "type": "#/components/schemas/TimeRange", "description": "The time range for filtering on the `closed_at` timestamp. If you use this\nvalue, you must set the `sort_field` in the `OrdersSearchSort` object to\n`CLOSED_AT`.", "readOnly": false, "required": false } ] }, { "name": "TimeRange", "properties": [ { "name": "start_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nstarts.", "readOnly": false, "required": false }, { "name": "end_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nends.", "readOnly": false, "required": false } ] }, { "name": "SearchOrdersFulfillmentFilter", "properties": [ { "name": "fulfillment_types", "type": "array", "description": "A list of [fulfillment types](entity:FulfillmentType) to filter\nfor. The list returns orders if any of its fulfillments match any of the fulfillment types\nlisted in this field.\n", "readOnly": false, "required": false, "arrayType": "#/components/schemas/FulfillmentType" }, { "name": "fulfillment_states", "type": "array", "description": "A list of [fulfillment states](entity:FulfillmentState) to filter\nfor. The list returns orders if any of its fulfillments match any of the\nfulfillment states listed in this field.\n", "readOnly": false, "required": false, "arrayType": "#/components/schemas/FulfillmentState" } ] }, { "name": "FulfillmentType", "properties": [] }, { "name": "FulfillmentState", "properties": [] }, { "name": "SearchOrdersSourceFilter", "properties": [ { "name": "source_names", "type": "array", "description": "Filters by the [Source](entity:OrderSource) `name`. The filter returns any orders\nwith a `source.name` that matches any of the listed source names.\n\nMax: 10 source names.", "readOnly": false, "required": false } ] }, { "name": "SearchOrdersCustomerFilter", "properties": [ { "name": "customer_ids", "type": "array", "description": "A list of customer IDs to filter by.\n\nMax: 10 customer ids.", "readOnly": false, "required": false } ] }, { "name": "SearchOrdersSort", "properties": [ { "name": "sort_field", "type": "#/components/schemas/SearchOrdersSortField", "description": "The field to sort by.\n\n__Important:__ When using a [DateTimeFilter](entity:SearchOrdersFilter),\n`sort_field` must match the timestamp field that the `DateTimeFilter` uses to\nfilter. For example, if you set your `sort_field` to `CLOSED_AT` and you use a\n`DateTimeFilter`, your `DateTimeFilter` must filter for orders by their `CLOSED_AT` date.\nIf this field does not match the timestamp field in `DateTimeFilter`,\n`SearchOrders` returns an error.\n\nDefault: `CREATED_AT`.\n", "readOnly": false, "required": true }, { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "The chronological order in which results are returned. Defaults to `DESC`.\n", "readOnly": false, "required": false } ] }, { "name": "SearchOrdersSortField", "properties": [] }, { "name": "SortOrder", "properties": [] } ], "RetrieveOrderRequest": [ { "name": "RetrieveOrderRequest", "properties": [ { "name": "order_id", "type": "string", "description": "The ID of the order to retrieve.", "readOnly": false, "required": true } ] } ], "UpdateOrderRequest": [ { "name": "UpdateOrderRequest", "properties": [ { "name": "order", "type": "#/components/schemas/Order", "description": "The [sparse order](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#sparse-order-objects)\ncontaining only the fields to update and the version to which the update is\nbeing applied.", "readOnly": false, "required": false }, { "name": "fields_to_clear", "type": "array", "description": "The [dot notation paths](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#identifying-fields-to-delete)\nfields to clear. For example, `line_items[uid].note`.\nFor more information, see [Deleting fields](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#deleting-fields).", "readOnly": false, "required": false }, { "name": "idempotency_key", "type": "string", "description": "A value you specify that uniquely identifies this update request.\n\nIf you are unsure whether a particular update was applied to an order successfully,\nyou can reattempt it with the same idempotency key without\nworrying about creating duplicate updates to the order.\nThe latest order version is returned.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the order to update.", "readOnly": false, "required": true } ] }, { "name": "Order", "properties": [ { "name": "id", "type": "string", "description": "The order's unique ID.", "readOnly": true, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the seller location that this order is associated with.", "readOnly": false, "required": true }, { "name": "reference_id", "type": "string", "description": "A client-specified ID to associate an entity in another system\nwith this order.", "readOnly": false, "required": false }, { "name": "source", "type": "#/components/schemas/OrderSource", "description": "The origination details of the order.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the [customer](entity:Customer) associated with the order.\n\nYou should specify a `customer_id` on the order (or the payment) to ensure that transactions\nare reliably linked to customers. Omitting this field might result in the creation of new\n[instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles).", "readOnly": false, "required": false }, { "name": "line_items", "type": "array", "description": "The line items included in the order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItem" }, { "name": "taxes", "type": "array", "description": "The list of all taxes associated with the order.\n\nTaxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an\n`OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes\nwith `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item.\n\nOn reads, each tax in the list includes the total amount of that tax applied to the order.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated\n`line_items.taxes` field results in an error. Use `line_items.applied_taxes`\ninstead.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemTax" }, { "name": "discounts", "type": "array", "description": "The list of all discounts associated with the order.\n\nDiscounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`,\nan `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to.\nFor discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount`\nfor every line item.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated\n`line_items.discounts` field results in an error. Use `line_items.applied_discounts`\ninstead.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemDiscount" }, { "name": "service_charges", "type": "array", "description": "A list of service charges applied to the order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderServiceCharge" }, { "name": "fulfillments", "type": "array", "description": "Details about order fulfillment.\n\nOrders can only be created with at most one fulfillment. However, orders returned\nby the API might contain multiple fulfillments.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Fulfillment" }, { "name": "returns", "type": "array", "description": "A collection of items from sale orders being returned in this one. Normally part of an\nitemized return or exchange. There is exactly one `Return` object per sale `Order` being\nreferenced.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturn" }, { "name": "return_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "The rollup of the returned money amounts.", "readOnly": true, "required": false }, { "name": "net_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "The net money amounts (sale money - return money).", "readOnly": true, "required": false }, { "name": "rounding_adjustment", "type": "#/components/schemas/OrderRoundingAdjustment", "description": "A positive rounding adjustment to the total of the order. This adjustment is commonly\nused to apply cash rounding when the minimum unit of account is smaller than the lowest physical\ndenomination of the currency.", "readOnly": true, "required": false }, { "name": "tenders", "type": "array", "description": "The tenders that were used to pay for the order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/Tender" }, { "name": "refunds", "type": "array", "description": "The refunds that are part of this order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/Refund" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp for when the order was created, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "closed_at", "type": "string", "description": "The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "state", "type": "#/components/schemas/OrderState", "description": "The current state of the order.\n", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The version number, which is incremented each time an update is committed to the order.\nOrders not created through the API do not include a version number and\ntherefore cannot be updated.\n\n[Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders).", "readOnly": false, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_tip_money", "type": "#/components/schemas/Money", "description": "The total amount of tip money to collect for the order.", "readOnly": true, "required": false }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of money collected in service charges for the order.\n\nNote: `total_service_charge_money` is the sum of `applied_money` fields for each individual\nservice charge. Therefore, `total_service_charge_money` only includes inclusive tax amounts,\nnot additive tax amounts.", "readOnly": true, "required": false }, { "name": "ticket_name", "type": "string", "description": "A short-term identifier for the order (such as a customer first name,\ntable number, or auto-generated order number that resets daily).", "readOnly": false, "required": false }, { "name": "pricing_options", "type": "#/components/schemas/OrderPricingOptions", "description": "Pricing options for an order. The options affect how the order's price is calculated.\nThey can be used, for example, to apply automatic price adjustments that are based on\npreconfigured [pricing rules](entity:CatalogPricingRule).", "readOnly": false, "required": false }, { "name": "rewards", "type": "array", "description": "A set-like list of Rewards that have been added to the Order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReward" }, { "name": "net_amount_due_money", "type": "#/components/schemas/Money", "description": "The net amount of money due on the order.", "readOnly": true, "required": false } ] }, { "name": "OrderSource", "properties": [ { "name": "name", "type": "string", "description": "The name used to identify the place (physical or digital) that an order originates.\nIf unset, the name defaults to the name of the application that created the order.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItem", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the line item only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the line item.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The count, or measurement, of a line item being purchased:\n\nIf `quantity` is a whole number, and `quantity_unit` is not specified, then `quantity` denotes an item count. For example: `3` apples.\n\nIf `quantity` is a whole or decimal number, and `quantity_unit` is also specified, then `quantity` denotes a measurement. For example: `2.25` pounds of broccoli.\n\nFor more information, see [Specify item quantity and measurement unit](https://developer.squareup.com/docs/orders-api/create-orders#specify-item-quantity-and-measurement-unit).\n\nLine items with a quantity of `0` are automatically removed\nwhen paying for or otherwise completing the order.", "readOnly": false, "required": true }, { "name": "quantity_unit", "type": "#/components/schemas/OrderQuantityUnit", "description": "The measurement unit and decimal precision that this line item's quantity is measured in.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "An optional note associated with the line item.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this line item.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item references.", "readOnly": false, "required": false }, { "name": "variation_name", "type": "string", "description": "The name of the variation applied to this line item.", "readOnly": false, "required": false }, { "name": "item_type", "type": "#/components/schemas/OrderLineItemItemType", "description": "The type of line item: an itemized sale, a non-itemized sale (custom amount), or the\nactivation or reloading of a gift card.\n", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this line item. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "modifiers", "type": "array", "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemModifier" }, { "name": "applied_taxes", "type": "array", "description": "The list of references to taxes applied to this line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a\ntop-level `OrderLineItemTax` applied to the line item. On reads, the\namount applied is populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every line\nitem for all `ORDER` scoped taxes added to the order. `OrderLineItemAppliedTax`\nrecords for `LINE_ITEM` scoped taxes must be added in requests for the tax\nto apply to any line items.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "applied_discounts", "type": "array", "description": "The list of references to discounts applied to this line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderLineItemDiscounts` applied to the line item. On reads, the amount\napplied is populated.\n\nAn `OrderLineItemAppliedDiscount` is automatically created on every line item for all\n`ORDER` scoped discounts that are added to the order. `OrderLineItemAppliedDiscount` records\nfor `LINE_ITEM` scoped discounts must be added in requests for the discount to apply to any\nline items.\n\nTo change the amount of a discount, modify the referenced top-level discount.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedDiscount" }, { "name": "applied_service_charges", "type": "array", "description": "The list of references to service charges applied to this line item. Each\n`OrderLineItemAppliedServiceCharge` has a `service_charge_id` that references the `uid` of a\ntop-level `OrderServiceCharge` applied to the line item. On reads, the amount applied is\npopulated.\n\nTo change the amount of a service charge, modify the referenced top-level service charge.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedServiceCharge" }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for a single unit of the line item.", "readOnly": false, "required": false }, { "name": "variation_total_price_money", "type": "#/components/schemas/Money", "description": "The total price of all item variations sold in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity`.\nIt does not include modifiers.", "readOnly": true, "required": false }, { "name": "gross_sales_money", "type": "#/components/schemas/Money", "description": "The amount of money made in gross sales for this line item.\nThe amount is calculated as the sum of the variation's total price and each modifier's total price.\nFor inclusive tax items in the US, Canada, and Japan, tax is deducted from `gross_sales_money`. For Europe and\nAustralia, inclusive tax remains as part of the gross sale calculation.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the line item.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to collect for the line item.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for this line item.", "readOnly": true, "required": false }, { "name": "pricing_blocklists", "type": "#/components/schemas/OrderLineItemPricingBlocklists", "description": "Describes pricing adjustments that are blocked from automatic\napplication to a line item. For more information, see\n[Apply Taxes and Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).", "readOnly": false, "required": false }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of apportioned service charge money to collect for the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderQuantityUnit", "properties": [ { "name": "measurement_unit", "type": "#/components/schemas/MeasurementUnit", "description": "A [MeasurementUnit](entity:MeasurementUnit) that represents the\nunit of measure for the quantity.", "readOnly": false, "required": false }, { "name": "precision", "type": "integer", "description": "For non-integer quantities, represents the number of digits after the decimal point that are\nrecorded for this quantity.\n\nFor example, a precision of 1 allows quantities such as `\"1.0\"` and `\"1.1\"`, but not `\"1.01\"`.\n\nMin: 0. Max: 5.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing the\n[CatalogMeasurementUnit](entity:CatalogMeasurementUnit).\n\nThis field is set when this is a catalog-backed measurement unit.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this measurement unit references.\n\nThis field is set when this is a catalog-backed measurement unit.", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnit", "properties": [ { "name": "custom_unit", "type": "#/components/schemas/MeasurementUnitCustom", "description": "A custom unit of measurement defined by the seller using the Point of Sale\napp or ad-hoc as an order line item.", "readOnly": false, "required": false }, { "name": "area_unit", "type": "#/components/schemas/MeasurementUnitArea", "description": "Represents a standard area unit.\n", "readOnly": false, "required": false }, { "name": "length_unit", "type": "#/components/schemas/MeasurementUnitLength", "description": "Represents a standard length unit.\n", "readOnly": false, "required": false }, { "name": "volume_unit", "type": "#/components/schemas/MeasurementUnitVolume", "description": "Represents a standard volume unit.\n", "readOnly": false, "required": false }, { "name": "weight_unit", "type": "#/components/schemas/MeasurementUnitWeight", "description": "Represents a standard unit of weight or mass.\n", "readOnly": false, "required": false }, { "name": "generic_unit", "type": "#/components/schemas/MeasurementUnitGeneric", "description": "Reserved for API integrations that lack the ability to specify a real measurement unit\n", "readOnly": false, "required": false }, { "name": "time_unit", "type": "#/components/schemas/MeasurementUnitTime", "description": "Represents a standard unit of time.\n", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/MeasurementUnitUnitType", "description": "Represents the type of the measurement unit.\n", "readOnly": false, "required": false } ] }, { "name": "MeasurementUnitCustom", "properties": [ { "name": "name", "type": "string", "description": "The name of the custom unit, for example \"bushel\".", "readOnly": false, "required": true }, { "name": "abbreviation", "type": "string", "description": "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears\nin the cart for the Point of Sale app, and in reports.", "readOnly": false, "required": true } ] }, { "name": "MeasurementUnitArea", "properties": [] }, { "name": "MeasurementUnitLength", "properties": [] }, { "name": "MeasurementUnitVolume", "properties": [] }, { "name": "MeasurementUnitWeight", "properties": [] }, { "name": "MeasurementUnitGeneric", "properties": [] }, { "name": "MeasurementUnitTime", "properties": [] }, { "name": "MeasurementUnitUnitType", "properties": [] }, { "name": "OrderLineItemItemType", "properties": [] }, { "name": "OrderLineItemModifier", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the modifier only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this modifier references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the item modifier.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0.", "readOnly": false, "required": false }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` will\noverride the predefined [CatalogModifier](entity:CatalogModifier) price.", "readOnly": false, "required": false }, { "name": "total_price_money", "type": "#/components/schemas/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "OrderLineItemAppliedTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied tax only within this order.", "readOnly": false, "required": false }, { "name": "tax_uid", "type": "string", "description": "The `uid` of the tax for which this applied tax represents. It must reference\na tax present in the `order.taxes` field.\n\nThis field is immutable. To change which taxes apply to a line item, delete and add a new\n`OrderLineItemAppliedTax`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the tax to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemAppliedDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied discount only within this order.", "readOnly": false, "required": false }, { "name": "discount_uid", "type": "string", "description": "The `uid` of the discount that the applied discount represents. It must\nreference a discount present in the `order.discounts` field.\n\nThis field is immutable. To change which discounts apply to a line item,\nyou must delete the discount and re-add it as a new `OrderLineItemAppliedDiscount`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the discount to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemAppliedServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the applied service charge only within this order.", "readOnly": false, "required": false }, { "name": "service_charge_uid", "type": "string", "description": "The `uid` of the service charge that the applied service charge represents. It must\nreference a service charge present in the `order.service_charges` field.\n\nThis field is immutable. To change which service charges apply to a line item,\ndelete and add a new `OrderLineItemAppliedServiceCharge`.", "readOnly": false, "required": true }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the service charge to the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemPricingBlocklists", "properties": [ { "name": "blocked_discounts", "type": "array", "description": "A list of discounts blocked from applying to the line item.\nDiscounts can be blocked by the `discount_uid` (for ad hoc discounts) or\nthe `discount_catalog_object_id` (for catalog discounts).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemPricingBlocklistsBlockedDiscount" }, { "name": "blocked_taxes", "type": "array", "description": "A list of taxes blocked from applying to the line item.\nTaxes can be blocked by the `tax_uid` (for ad hoc taxes) or\nthe `tax_catalog_object_id` (for catalog taxes).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemPricingBlocklistsBlockedTax" } ] }, { "name": "OrderLineItemPricingBlocklistsBlockedDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID of the `BlockedDiscount` within the order.", "readOnly": false, "required": false }, { "name": "discount_uid", "type": "string", "description": "The `uid` of the discount that should be blocked. Use this field to block\nad hoc discounts. For catalog discounts, use the `discount_catalog_object_id` field.", "readOnly": false, "required": false }, { "name": "discount_catalog_object_id", "type": "string", "description": "The `catalog_object_id` of the discount that should be blocked.\nUse this field to block catalog discounts. For ad hoc discounts, use the\n`discount_uid` field.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItemPricingBlocklistsBlockedTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID of the `BlockedTax` within the order.", "readOnly": false, "required": false }, { "name": "tax_uid", "type": "string", "description": "The `uid` of the tax that should be blocked. Use this field to block\nad hoc taxes. For catalog, taxes use the `tax_catalog_object_id` field.", "readOnly": false, "required": false }, { "name": "tax_catalog_object_id", "type": "string", "description": "The `catalog_object_id` of the tax that should be blocked.\nUse this field to block catalog taxes. For ad hoc taxes, use the\n`tax_uid` field.", "readOnly": false, "required": false } ] }, { "name": "OrderLineItemTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the tax only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this tax references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The tax's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal\nnumber. For example, a value of `\"7.25\"` corresponds to a percentage of\n7.25%.", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this tax. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the tax.\n\n- For percentage-based taxes, `applied_money` is the money\ncalculated using the percentage.", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemTaxScope", "description": "Indicates the level at which the tax applies. For `ORDER` scoped taxes,\nSquare generates references in `applied_taxes` on all order line items that do\nnot have them. For `LINE_ITEM` scoped taxes, the tax only applies to line items\nwith references in their `applied_taxes` field.\n\nThis field is immutable. To change the scope, you must delete the tax and\nre-add it as a new tax.\n", "readOnly": false, "required": false }, { "name": "auto_applied", "type": "boolean", "description": "Determines whether the tax was automatically applied to the order based on\nthe catalog configuration. For an example, see\n[Automatically Apply Taxes to an Order](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes).", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemTaxType", "properties": [] }, { "name": "OrderLineItemTaxScope", "properties": [] }, { "name": "OrderLineItemDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the discount only within this order.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this discount references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The discount's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemDiscountType", "description": "The type of the discount.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the discount, as a string representation of a decimal number.\nA value of `7.25` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of discount actually applied to the line item.\n\nThe amount represents the amount of money applied as a line-item scoped discount.\nWhen an amount-based discount is scoped to the entire order, the value\nof `applied_money` is different than `amount_money` because the total\namount of the discount is distributed across all line items.", "readOnly": false, "required": false }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this discount. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemDiscountScope", "description": "Indicates the level at which the discount applies. For `ORDER` scoped discounts,\nSquare generates references in `applied_discounts` on all order line items that do\nnot have them. For `LINE_ITEM` scoped discounts, the discount only applies to line items\nwith a discount reference in their `applied_discounts` field.\n\nThis field is immutable. To change the scope of a discount, you must delete\nthe discount and re-add it as a new discount.\n", "readOnly": false, "required": false }, { "name": "reward_ids", "type": "array", "description": "The reward IDs corresponding to this discount. The application and\nspecification of discounts that have `reward_ids` are completely controlled by the backing\ncriteria corresponding to the reward tiers of the rewards that are added to the order\nthrough the Loyalty API. To manually unapply discounts that are the result of added rewards,\nthe rewards must be removed from the order through the Loyalty API.", "readOnly": true, "required": false }, { "name": "pricing_rule_id", "type": "string", "description": "The object ID of a [pricing rule](entity:CatalogPricingRule) to be applied\nautomatically to this discount. The specification and application of the discounts, to\nwhich a `pricing_rule_id` is assigned, are completely controlled by the corresponding\npricing rule.", "readOnly": true, "required": false } ] }, { "name": "OrderLineItemDiscountType", "properties": [] }, { "name": "OrderLineItemDiscountScope", "properties": [] }, { "name": "OrderServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the service charge only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the service charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing the service charge [CatalogObject](entity:CatalogObject).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this service charge references.", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The service charge percentage as a string representation of a\ndecimal number. For example, `\"7.25\"` indicates a service charge of 7.25%.\n\nExactly 1 of `percentage` or `amount_money` should be set.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of a non-percentage-based service charge.\n\nExactly one of `percentage` or `amount_money` should be set.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the service charge,\nincluding any inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money\ncalculated using the percentage.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the service charge.\n\n__Note__: If an inclusive tax is applied to the service charge,\n`total_money` does not equal `applied_money` plus `total_tax_money`\nbecause the inclusive tax amount is already included in both\n`applied_money` and `total_tax_money`.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/OrderServiceChargeCalculationPhase", "description": "The calculation phase at which to apply the service charge.\n", "readOnly": false, "required": false }, { "name": "taxable", "type": "boolean", "description": "Indicates whether the service charge can be taxed. If set to `true`,\norder-level taxes automatically apply to the service charge. Note that\nservice charges calculated in the `TOTAL_PHASE` cannot be marked as taxable.", "readOnly": false, "required": false }, { "name": "applied_taxes", "type": "array", "description": "The list of references to the taxes applied to this service charge. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderLineItemTax` that is being applied to this service charge. On reads, the amount applied\nis populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every taxable service charge\nfor all `ORDER` scoped taxes that are added to the order. `OrderLineItemAppliedTax` records\nfor `LINE_ITEM` scoped taxes must be added in requests for the tax to apply to any taxable\nservice charge. Taxable service charges have the `taxable` field set to `true` and calculated\nin the `SUBTOTAL_PHASE`.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this service charge. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderServiceChargeType", "description": "The type of the service charge.\n", "readOnly": true, "required": false }, { "name": "treatment_type", "type": "#/components/schemas/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\n", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\n", "readOnly": false, "required": false } ] }, { "name": "OrderServiceChargeCalculationPhase", "properties": [] }, { "name": "OrderServiceChargeType", "properties": [] }, { "name": "OrderServiceChargeTreatmentType", "properties": [] }, { "name": "OrderServiceChargeScope", "properties": [] }, { "name": "Fulfillment", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the fulfillment only within this order.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/FulfillmentType", "description": "The type of the fulfillment.\n", "readOnly": false, "required": false }, { "name": "state", "type": "#/components/schemas/FulfillmentState", "description": "The state of the fulfillment.\n", "readOnly": false, "required": false }, { "name": "line_item_application", "type": "#/components/schemas/FulfillmentFulfillmentLineItemApplication", "description": "Describes what order line items this fulfillment applies to.\nIt can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.\n", "readOnly": true, "required": false }, { "name": "entries", "type": "array", "description": "A list of entries pertaining to the fulfillment of an order. Each entry must reference\na valid `uid` for an order line item in the `line_item_uid` field, as well as a `quantity` to\nfulfill.\n\nMultiple entries can reference the same line item `uid`, as long as the total quantity among\nall fulfillment entries referencing a single line item does not exceed the quantity of the\norder's line item itself.\n\nAn order cannot be marked as `COMPLETED` before all fulfillments are `COMPLETED`,\n`CANCELED`, or `FAILED`. Fulfillments can be created and completed independently\nbefore order completion.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/FulfillmentFulfillmentEntry" }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this fulfillment. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false }, { "name": "pickup_details", "type": "#/components/schemas/FulfillmentPickupDetails", "description": "Contains details for a pickup fulfillment. These details are required when the fulfillment\ntype is `PICKUP`.", "readOnly": false, "required": false }, { "name": "shipment_details", "type": "#/components/schemas/FulfillmentShipmentDetails", "description": "Contains details for a shipment fulfillment. These details are required when the fulfillment type\nis `SHIPMENT`.\n\nA shipment fulfillment's relationship to fulfillment `state`:\n`PROPOSED`: A shipment is requested.\n`RESERVED`: Fulfillment in progress. Shipment processing.\n`PREPARED`: Shipment packaged. Shipping label created.\n`COMPLETED`: Package has been shipped.\n`CANCELED`: Shipment has been canceled.\n`FAILED`: Shipment has failed.", "readOnly": false, "required": false }, { "name": "delivery_details", "type": "#/components/schemas/FulfillmentDeliveryDetails", "description": "Describes delivery details of an order fulfillment.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentType", "properties": [] }, { "name": "FulfillmentState", "properties": [] }, { "name": "FulfillmentFulfillmentLineItemApplication", "properties": [] }, { "name": "FulfillmentFulfillmentEntry", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the fulfillment entry only within this order.", "readOnly": false, "required": false }, { "name": "line_item_uid", "type": "string", "description": "The `uid` from the order line item.", "readOnly": false, "required": true }, { "name": "quantity", "type": "string", "description": "The quantity of the line item being fulfilled, formatted as a decimal number.\nFor example, `\"3\"`.\n\nFulfillments for line items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "readOnly": false, "required": true }, { "name": "metadata", "type": "map", "description": "Application-defined data attached to this fulfillment entry. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "readOnly": false, "required": false } ] }, { "name": "FulfillmentPickupDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "Information about the person to pick up this fulfillment from a physical\nlocation.", "readOnly": false, "required": false }, { "name": "expires_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment expires if it is not marked in progress. The timestamp must be\nin RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\"). The expiration time can only be set\nup to 7 days in the future. If `expires_at` is not set, any new payments attached to the order\nare automatically completed.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "auto_complete_duration", "type": "string", "description": "The duration of time after which an in progress pickup fulfillment is automatically moved\nto the `COMPLETED` state. The duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nIf not set, this pickup fulfillment remains in progress until it is canceled or completed.\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "schedule_type", "type": "#/components/schemas/FulfillmentPickupDetailsScheduleType", "description": "The schedule type of the pickup fulfillment. Defaults to `SCHEDULED`.\n", "readOnly": false, "required": false }, { "name": "pickup_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the pickup window. Must be in RFC 3339 timestamp format, e.g.,\n\"2016-09-04T23:59:33.123Z\".\n\nFor fulfillments with the schedule type `ASAP`, this is automatically set\nto the current time plus the expected duration to prepare the fulfillment.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "pickup_window_duration", "type": "string", "description": "The window of time in which the order should be picked up after the `pickup_at` timestamp.\nMust be in RFC 3339 duration format, e.g., \"P1W3D\". Can be used as an\ninformational guideline for merchants.\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "prep_time_duration", "type": "string", "description": "The duration of time it takes to prepare this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "A note to provide additional instructions about the pickup\nfulfillment displayed in the Square Point of Sale application and set by the API.", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "accepted_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was marked in progress. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "rejected_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "ready_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment is marked as ready for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "expired_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment expired. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "picked_up_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was picked up by the recipient. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "string", "description": "A description of why the pickup was canceled. The maximum length: 100 characters.", "readOnly": false, "required": false }, { "name": "is_curbside_pickup", "type": "boolean", "description": "If set to `true`, indicates that this pickup order is for curbside pickup, not in-store pickup.", "readOnly": false, "required": false }, { "name": "curbside_pickup_details", "type": "#/components/schemas/FulfillmentPickupDetailsCurbsidePickupDetails", "description": "Specific details for curbside pickup. These details can only be populated if `is_curbside_pickup` is set to `true`.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentRecipient", "properties": [ { "name": "customer_id", "type": "string", "description": "The ID of the customer associated with the fulfillment.\n\nIf `customer_id` is provided, the fulfillment recipient's `display_name`,\n`email_address`, and `phone_number` are automatically populated from the\ntargeted customer profile. If these fields are set in the request, the request\nvalues override the information from the customer profile. If the\ntargeted customer profile does not contain the necessary information and\nthese fields are left unset, the request results in an error.", "readOnly": false, "required": false }, { "name": "display_name", "type": "string", "description": "The display name of the fulfillment recipient. This field is required.\n\nIf provided, the display name overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "email_address", "type": "string", "description": "The email address of the fulfillment recipient.\n\nIf provided, the email address overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number of the fulfillment recipient. This field is required.\n\nIf provided, the phone number overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The address of the fulfillment recipient. This field is required.\n\nIf provided, the address overrides the corresponding customer profile value\nindicated by `customer_id`.", "readOnly": false, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "FulfillmentPickupDetailsScheduleType", "properties": [] }, { "name": "FulfillmentPickupDetailsCurbsidePickupDetails", "properties": [ { "name": "curbside_details", "type": "string", "description": "Specific details for curbside pickup, such as parking number and vehicle model.", "readOnly": false, "required": false }, { "name": "buyer_arrived_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the buyer arrived and is waiting for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false } ] }, { "name": "FulfillmentShipmentDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "Information about the person to receive this shipment fulfillment.", "readOnly": false, "required": false }, { "name": "carrier", "type": "string", "description": "The shipping carrier being used to ship this fulfillment (such as UPS, FedEx, or USPS).", "readOnly": false, "required": false }, { "name": "shipping_note", "type": "string", "description": "A note with additional information for the shipping carrier.", "readOnly": false, "required": false }, { "name": "shipping_type", "type": "string", "description": "A description of the type of shipping product purchased from the carrier\n(such as First Class, Priority, or Express).", "readOnly": false, "required": false }, { "name": "tracking_number", "type": "string", "description": "The reference number provided by the carrier to track the shipment's progress.", "readOnly": false, "required": false }, { "name": "tracking_url", "type": "string", "description": "A link to the tracking webpage on the carrier's website.", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment was requested. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "in_progress_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `RESERVED` state, which indicates that preparation\nof this shipment has begun. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "packaged_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `PREPARED` state, which indicates that the\nfulfillment is packaged. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "expected_shipped_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment is expected to be delivered to the shipping carrier.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "shipped_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `COMPLETED` state, which indicates that\nthe fulfillment has been given to the shipping carrier. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating the shipment was canceled.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "cancel_reason", "type": "string", "description": "A description of why the shipment was canceled.", "readOnly": false, "required": false }, { "name": "failed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment failed to be completed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "failure_reason", "type": "string", "description": "A description of why the shipment failed to be completed.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentDeliveryDetails", "properties": [ { "name": "recipient", "type": "#/components/schemas/FulfillmentRecipient", "description": "The contact information for the person to receive the fulfillment.", "readOnly": false, "required": false }, { "name": "schedule_type", "type": "#/components/schemas/FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType", "description": "Indicates the fulfillment delivery schedule type. If `SCHEDULED`, then\n`deliver_at` is required. If `ASAP`, then `prep_time_duration` is required. The default is `SCHEDULED`.\n", "readOnly": false, "required": false }, { "name": "placed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nMust be in RFC 3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "deliver_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the delivery period.\nWhen the fulfillment `schedule_type` is `ASAP`, the field is automatically\nset to the current time plus the `prep_time_duration`.\nOtherwise, the application can set this field while the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the\nterminal state such as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "prep_time_duration", "type": "string", "description": "The duration of time it takes to prepare and deliver this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "delivery_window_duration", "type": "string", "description": "The time period after `deliver_at` in which to deliver the order.\nApplications can set this field when the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the terminal state\nsuch as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "Provides additional instructions about the delivery fulfillment.\nIt is displayed in the Square Point of Sale application and set by the API.", "readOnly": false, "required": false }, { "name": "completed_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller completed the fulfillment.\nThis field is automatically set when fulfillment `state` changes to `COMPLETED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "in_progress_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller started processing the fulfillment.\nThis field is automatically set when the fulfillment `state` changes to `RESERVED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "rejected_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. This field is\nautomatically set when the fulfillment `state` changes to `FAILED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "ready_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the seller marked the fulfillment as ready for\ncourier pickup. This field is automatically set when the fulfillment `state` changes\nto PREPARED.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "delivered_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was delivered to the recipient.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "canceled_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. This field is automatically\nset when the fulfillment `state` changes to `CANCELED`.\n\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "string", "description": "The delivery cancellation reason. Max length: 100 characters.", "readOnly": false, "required": false }, { "name": "courier_pickup_at", "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when an order can be picked up by the courier for delivery.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "courier_pickup_window_duration", "type": "string", "description": "The time period after `courier_pickup_at` in which the courier should pick up the order.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "is_no_contact_delivery", "type": "boolean", "description": "Whether the delivery is preferred to be no contact.", "readOnly": false, "required": false }, { "name": "dropoff_notes", "type": "string", "description": "A note to provide additional instructions about how to deliver the order.", "readOnly": false, "required": false }, { "name": "courier_provider_name", "type": "string", "description": "The name of the courier provider.", "readOnly": false, "required": false }, { "name": "courier_support_phone_number", "type": "string", "description": "The support phone number of the courier.", "readOnly": false, "required": false }, { "name": "square_delivery_id", "type": "string", "description": "The identifier for the delivery created by Square.", "readOnly": false, "required": false }, { "name": "external_delivery_id", "type": "string", "description": "The identifier for the delivery created by the third-party courier service.", "readOnly": false, "required": false }, { "name": "managed_delivery", "type": "boolean", "description": "The flag to indicate the delivery is managed by a third party (ie DoorDash), which means\nwe may not receive all recipient information for PII purposes.", "readOnly": false, "required": false } ] }, { "name": "FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType", "properties": [] }, { "name": "OrderReturn", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return only within this order.", "readOnly": false, "required": false }, { "name": "source_order_id", "type": "string", "description": "An order that contains the original sale of these return line items. This is unset\nfor unlinked returns.", "readOnly": false, "required": false }, { "name": "return_line_items", "type": "array", "description": "A collection of line items that are being returned.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnLineItem" }, { "name": "return_service_charges", "type": "array", "description": "A collection of service charges that are being returned.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnServiceCharge" }, { "name": "return_taxes", "type": "array", "description": "A collection of references to taxes being returned for an order, including the total\napplied tax amount to be returned. The taxes must reference a top-level tax ID from the source\norder.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturnTax" }, { "name": "return_discounts", "type": "array", "description": "A collection of references to discounts being returned for an order, including the total\napplied discount amount to be returned. The discounts must reference a top-level discount ID\nfrom the source order.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/OrderReturnDiscount" }, { "name": "return_tips", "type": "array", "description": "A collection of references to tips being returned for an order.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnTip" }, { "name": "rounding_adjustment", "type": "#/components/schemas/OrderRoundingAdjustment", "description": "A positive or negative rounding adjustment to the total value being returned. Adjustments are commonly\nused to apply cash rounding when the minimum unit of the account is smaller than the lowest\nphysical denomination of the currency.", "readOnly": false, "required": false }, { "name": "return_amounts", "type": "#/components/schemas/OrderMoneyAmounts", "description": "An aggregate monetary value being returned by this return entry.", "readOnly": false, "required": false } ] }, { "name": "OrderReturnLineItem", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID for this return line-item entry.", "readOnly": false, "required": false }, { "name": "source_line_item_uid", "type": "string", "description": "The `uid` of the line item in the original sale order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the line item.", "readOnly": false, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity returned, formatted as a decimal number.\nFor example, `\"3\"`.\n\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "readOnly": false, "required": true }, { "name": "quantity_unit", "type": "#/components/schemas/OrderQuantityUnit", "description": "The unit and precision that this return line item's quantity is measured in.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "The note of the return line item.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this return line item.", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item references.", "readOnly": false, "required": false }, { "name": "variation_name", "type": "string", "description": "The name of the variation applied to this return line item.", "readOnly": false, "required": false }, { "name": "item_type", "type": "#/components/schemas/OrderLineItemItemType", "description": "The type of line item: an itemized return, a non-itemized return (custom amount),\nor the return of an unactivated gift card sale.\n", "readOnly": false, "required": false }, { "name": "return_modifiers", "type": "array", "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderReturnLineItemModifier" }, { "name": "applied_taxes", "type": "array", "description": "The list of references to `OrderReturnTax` entities applied to the return line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderReturnTax` applied to the return line item. On reads, the applied amount\nis populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "applied_discounts", "type": "array", "description": "The list of references to `OrderReturnDiscount` entities applied to the return line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderReturnDiscount` applied to the return line item. On reads, the applied amount\nis populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedDiscount" }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for a single unit of the line item.", "readOnly": false, "required": false }, { "name": "variation_total_price_money", "type": "#/components/schemas/Money", "description": "The total price of all item variations returned in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity` and\ndoes not include modifiers.", "readOnly": true, "required": false }, { "name": "gross_return_money", "type": "#/components/schemas/Money", "description": "The gross return amount of money calculated as (item base price + modifiers price) * quantity.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to return for the line item.", "readOnly": true, "required": false }, { "name": "total_discount_money", "type": "#/components/schemas/Money", "description": "The total amount of discount money to return for the line item.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to return for this line item.", "readOnly": true, "required": false }, { "name": "applied_service_charges", "type": "array", "description": "The list of references to `OrderReturnServiceCharge` entities applied to the return\nline item. Each `OrderLineItemAppliedServiceCharge` has a `service_charge_uid` that\nreferences the `uid` of a top-level `OrderReturnServiceCharge` applied to the return line\nitem. On reads, the applied amount is populated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedServiceCharge" }, { "name": "total_service_charge_money", "type": "#/components/schemas/Money", "description": "The total amount of apportioned service charge money to return for the line item.", "readOnly": true, "required": false } ] }, { "name": "OrderReturnLineItemModifier", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return modifier only within this order.", "readOnly": false, "required": false }, { "name": "source_modifier_uid", "type": "string", "description": "The modifier `uid` from the order's line item that contains the\noriginal sale of this line item modifier.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this line item modifier references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the item modifier.", "readOnly": false, "required": false }, { "name": "base_price_money", "type": "#/components/schemas/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` overrides the predefined [CatalogModifier](entity:CatalogModifier) price.", "readOnly": false, "required": false }, { "name": "total_price_money", "type": "#/components/schemas/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true, "required": false }, { "name": "quantity", "type": "string", "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0.", "readOnly": false, "required": false } ] }, { "name": "OrderReturnServiceCharge", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the return service charge only within this order.", "readOnly": false, "required": false }, { "name": "source_service_charge_uid", "type": "string", "description": "The service charge `uid` from the order containing the original\nservice charge. `source_service_charge_uid` is `null` for\nunlinked returns.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the service charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID of the associated [OrderServiceCharge](entity:OrderServiceCharge).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this service charge references.", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "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%.\n\nEither `percentage` or `amount_money` should be set, but not both.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of a non-percentage-based service charge.\n\nEither `percentage` or `amount_money` should be set, but not both.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied to the order by the service charge, including\nany inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money calculated using the percentage.", "readOnly": true, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount of money to collect for the service charge.\n\n__NOTE__: If an inclusive tax is applied to the service charge, `total_money`\ndoes not equal `applied_money` plus `total_tax_money` because the inclusive\ntax amount is already included in both `applied_money` and `total_tax_money`.", "readOnly": true, "required": false }, { "name": "total_tax_money", "type": "#/components/schemas/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true, "required": false }, { "name": "calculation_phase", "type": "#/components/schemas/OrderServiceChargeCalculationPhase", "description": "The calculation phase after which to apply the service charge.\n", "readOnly": true, "required": false }, { "name": "taxable", "type": "boolean", "description": "Indicates whether the surcharge can be taxed. Service charges\ncalculated in the `TOTAL_PHASE` cannot be marked as taxable.", "readOnly": false, "required": false }, { "name": "applied_taxes", "type": "array", "description": "The list of references to `OrderReturnTax` entities applied to the\n`OrderReturnServiceCharge`. Each `OrderLineItemAppliedTax` has a `tax_uid`\nthat references the `uid` of a top-level `OrderReturnTax` that is being\napplied to the `OrderReturnServiceCharge`. On reads, the applied amount is\npopulated.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/OrderLineItemAppliedTax" }, { "name": "treatment_type", "type": "#/components/schemas/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\n", "readOnly": false, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnTax", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the returned tax only within this order.", "readOnly": false, "required": false }, { "name": "source_tax_uid", "type": "string", "description": "The tax `uid` from the order that contains the original tax charge.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this tax references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The tax's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal number.\nFor example, a value of `\"7.25\"` corresponds to a percentage of 7.25%.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of money applied by the tax in an order.", "readOnly": true, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemTaxScope", "description": "Indicates the level at which the `OrderReturnTax` applies. For `ORDER` scoped\ntaxes, Square generates references in `applied_taxes` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnDiscount", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the returned discount only within this order.", "readOnly": false, "required": false }, { "name": "source_discount_uid", "type": "string", "description": "The discount `uid` from the order that contains the original application of this discount.", "readOnly": false, "required": false }, { "name": "catalog_object_id", "type": "string", "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "readOnly": false, "required": false }, { "name": "catalog_version", "type": "integer", "description": "The version of the catalog object that this discount references.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The discount's name.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/OrderLineItemDiscountType", "description": "The type of the discount. If it is created by the API, it is `FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n", "readOnly": false, "required": false }, { "name": "percentage", "type": "string", "description": "The percentage of the tax, as a string representation of a decimal number.\nA value of `\"7.25\"` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of discount actually applied to this line item. When an amount-based\ndiscount is at the order level, this value is different from `amount_money` because the discount\nis distributed across the line items.", "readOnly": true, "required": false }, { "name": "scope", "type": "#/components/schemas/OrderLineItemDiscountScope", "description": "Indicates the level at which the `OrderReturnDiscount` applies. For `ORDER` scoped\ndiscounts, the server generates references in `applied_discounts` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the discount is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\n", "readOnly": false, "required": false } ] }, { "name": "OrderReturnTip", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the tip only within this order.", "readOnly": false, "required": false }, { "name": "applied_money", "type": "#/components/schemas/Money", "description": "The amount of tip being returned\n--", "readOnly": true, "required": false }, { "name": "source_tender_uid", "type": "string", "description": "The tender `uid` from the order that contains the original application of this tip.", "readOnly": false, "required": false }, { "name": "source_tender_id", "type": "string", "description": "The tender `id` from the order that contains the original application of this tip.", "readOnly": false, "required": false } ] }, { "name": "OrderRoundingAdjustment", "properties": [ { "name": "uid", "type": "string", "description": "A unique ID that identifies the rounding adjustment only within this order.", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the rounding adjustment from the original sale order.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The actual rounding adjustment amount.", "readOnly": false, "required": false } ] }, { "name": "OrderMoneyAmounts", "properties": [ { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total money.", "readOnly": false, "required": false }, { "name": "tax_money", "type": "#/components/schemas/Money", "description": "The money associated with taxes.", "readOnly": false, "required": false }, { "name": "discount_money", "type": "#/components/schemas/Money", "description": "The money associated with discounts.", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The money associated with tips.", "readOnly": false, "required": false }, { "name": "service_charge_money", "type": "#/components/schemas/Money", "description": "The money associated with service charges.", "readOnly": false, "required": false } ] }, { "name": "Tender", "properties": [ { "name": "id", "type": "string", "description": "The tender's unique ID. It is the associated payment ID.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the transaction's associated location.", "readOnly": false, "required": false }, { "name": "transaction_id", "type": "string", "description": "The ID of the tender's associated transaction.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp for when the tender was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "note", "type": "string", "description": "An optional note associated with the tender at the time of payment.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The total amount of the tender, including `tip_money`. If the tender has a `payment_id`,\nthe `total_money` of the corresponding [Payment](entity:Payment) will be equal to the\n`amount_money` of the tender.", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The tip's amount of the tender.", "readOnly": false, "required": false }, { "name": "processing_fee_money", "type": "#/components/schemas/Money", "description": "The amount of any Square processing fees applied to the tender.\n\nThis field is not immediately populated when a new transaction is created.\nIt is usually available after about ten seconds.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "If the tender is associated with a customer or represents a customer's card on file,\nthis is the ID of the associated customer.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/TenderType", "description": "The type of tender, such as `CARD` or `CASH`.\n", "readOnly": false, "required": true }, { "name": "card_details", "type": "#/components/schemas/TenderCardDetails", "description": "The details of the card tender.\n\nThis value is present only if the value of `type` is `CARD`.", "readOnly": false, "required": false }, { "name": "cash_details", "type": "#/components/schemas/TenderCashDetails", "description": "The details of the cash tender.\n\nThis value is present only if the value of `type` is `CASH`.", "readOnly": false, "required": false }, { "name": "bank_account_details", "type": "#/components/schemas/TenderBankAccountDetails", "description": "The details of the bank account tender.\n\nThis value is present only if the value of `type` is `BANK_ACCOUNT`.", "readOnly": false, "required": false }, { "name": "buy_now_pay_later_details", "type": "#/components/schemas/TenderBuyNowPayLaterDetails", "description": "The details of a Buy Now Pay Later tender.\n\nThis value is present only if the value of `type` is `BUY_NOW_PAY_LATER`.", "readOnly": false, "required": false }, { "name": "square_account_details", "type": "#/components/schemas/TenderSquareAccountDetails", "description": "The details of a Square Account tender.\n\nThis value is present only if the value of `type` is `SQUARE_ACCOUNT`.", "readOnly": false, "required": false }, { "name": "additional_recipients", "type": "array", "description": "Additional recipients (other than the merchant) receiving a portion of this tender.\nFor example, fees assessed on the purchase by a third party integration.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/AdditionalRecipient" }, { "name": "payment_id", "type": "string", "description": "The ID of the [Payment](entity:Payment) that corresponds to this tender.\nThis value is only present for payments created with the v2 Payments API.", "readOnly": false, "required": false } ] }, { "name": "TenderType", "properties": [] }, { "name": "TenderCardDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderCardDetailsStatus", "description": "The credit card payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderCardDetailsStatus](entity:TenderCardDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false }, { "name": "card", "type": "#/components/schemas/Card", "description": "The credit card's non-confidential details.", "readOnly": false, "required": false }, { "name": "entry_method", "type": "#/components/schemas/TenderCardDetailsEntryMethod", "description": "The method used to enter the card's details for the transaction.\n", "readOnly": false, "required": false } ] }, { "name": "TenderCardDetailsStatus", "properties": [] }, { "name": "Card", "properties": [ { "name": "id", "type": "string", "description": "Unique ID for this card. Generated by Square.", "readOnly": true, "required": false }, { "name": "card_brand", "type": "#/components/schemas/CardBrand", "description": "The card's brand.\n", "readOnly": true, "required": false }, { "name": "last_4", "type": "string", "description": "The last 4 digits of the card number.", "readOnly": true, "required": false }, { "name": "exp_month", "type": "integer", "description": "The expiration month of the associated card as an integer between 1 and 12.", "readOnly": false, "required": false }, { "name": "exp_year", "type": "integer", "description": "The four-digit year of the card's expiration date.", "readOnly": false, "required": false }, { "name": "cardholder_name", "type": "string", "description": "The name of the cardholder.", "readOnly": false, "required": false }, { "name": "billing_address", "type": "#/components/schemas/Address", "description": "The billing address for this card.", "readOnly": false, "required": false }, { "name": "fingerprint", "type": "string", "description": "Intended as a Square-assigned identifier, based\non the card number, to identify the card across multiple locations within a\nsingle application.", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "**Required** The ID of a customer created using the Customers API to be associated with the card.", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the merchant associated with the card.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional user-defined reference ID that associates this card with\nanother entity in an external system. For example, a customer ID from an\nexternal customer management system.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "Indicates whether or not a card can be used for payments.", "readOnly": true, "required": false }, { "name": "card_type", "type": "#/components/schemas/CardType", "description": "The type of the card.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "prepaid_type", "type": "#/components/schemas/CardPrepaidType", "description": "Indicates whether the Card is prepaid or not.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "bin", "type": "string", "description": "The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API\nreturns this field.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "Current version number of the card. Increments with each card update. Requests to update an\nexisting Card object will be rejected unless the version in the request matches the current\nversion for the Card.", "readOnly": false, "required": false }, { "name": "card_co_brand", "type": "#/components/schemas/CardCoBrand", "description": "The card's co-brand if available. For example, an Afterpay virtual card would have a\nco-brand of AFTERPAY.\n", "readOnly": true, "required": false } ] }, { "name": "CardBrand", "properties": [] }, { "name": "CardType", "properties": [] }, { "name": "CardPrepaidType", "properties": [] }, { "name": "CardCoBrand", "properties": [] }, { "name": "TenderCardDetailsEntryMethod", "properties": [] }, { "name": "TenderCashDetails", "properties": [ { "name": "buyer_tendered_money", "type": "#/components/schemas/Money", "description": "The total amount of cash provided by the buyer, before change is given.", "readOnly": false, "required": false }, { "name": "change_back_money", "type": "#/components/schemas/Money", "description": "The amount of change returned to the buyer.", "readOnly": false, "required": false } ] }, { "name": "TenderBankAccountDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderBankAccountDetailsStatus", "description": "The bank account payment's current state.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "TenderBankAccountDetailsStatus", "properties": [] }, { "name": "TenderBuyNowPayLaterDetails", "properties": [ { "name": "buy_now_pay_later_brand", "type": "#/components/schemas/TenderBuyNowPayLaterDetailsBrand", "description": "The Buy Now Pay Later brand.\n", "readOnly": true, "required": false }, { "name": "status", "type": "#/components/schemas/TenderBuyNowPayLaterDetailsStatus", "description": "The buy now pay later payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderBuyNowPayLaterDetailsStatus](entity:TenderBuyNowPayLaterDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false } ] }, { "name": "TenderBuyNowPayLaterDetailsBrand", "properties": [] }, { "name": "TenderBuyNowPayLaterDetailsStatus", "properties": [] }, { "name": "TenderSquareAccountDetails", "properties": [ { "name": "status", "type": "#/components/schemas/TenderSquareAccountDetailsStatus", "description": "The Square Account payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderSquareAccountDetailsStatus](entity:TenderSquareAccountDetailsStatus)\nfor possible values.\n", "readOnly": false, "required": false } ] }, { "name": "TenderSquareAccountDetailsStatus", "properties": [] }, { "name": "AdditionalRecipient", "properties": [ { "name": "location_id", "type": "string", "description": "The location ID for a recipient (other than the merchant) receiving a portion of this tender.", "readOnly": false, "required": true }, { "name": "description", "type": "string", "description": "The description of the additional recipient.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money distributed to the recipient.", "readOnly": false, "required": true }, { "name": "receivable_id", "type": "string", "description": "The unique ID for the RETIRED `AdditionalRecipientReceivable` object. This field should be empty for any `AdditionalRecipient` objects created after the retirement.", "readOnly": false, "required": false } ] }, { "name": "Refund", "properties": [ { "name": "id", "type": "string", "description": "The refund's unique ID.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The ID of the refund's associated location.", "readOnly": false, "required": true }, { "name": "transaction_id", "type": "string", "description": "The ID of the transaction that the refunded tender is part of.", "readOnly": false, "required": false }, { "name": "tender_id", "type": "string", "description": "The ID of the refunded tender.", "readOnly": false, "required": true }, { "name": "created_at", "type": "string", "description": "The timestamp for when the refund was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "reason", "type": "string", "description": "The reason for the refund being issued.", "readOnly": false, "required": true }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money refunded to the buyer.", "readOnly": false, "required": true }, { "name": "status", "type": "#/components/schemas/RefundStatus", "description": "The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`,\nor `FAILED`).\n", "readOnly": false, "required": true }, { "name": "processing_fee_money", "type": "#/components/schemas/Money", "description": "The amount of Square processing fee money refunded to the *merchant*.", "readOnly": false, "required": false }, { "name": "additional_recipients", "type": "array", "description": "Additional recipients (other than the merchant) receiving a portion of this refund.\nFor example, fees assessed on a refund of a purchase by a third party integration.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/AdditionalRecipient" } ] }, { "name": "RefundStatus", "properties": [] }, { "name": "OrderState", "properties": [] }, { "name": "OrderPricingOptions", "properties": [ { "name": "auto_apply_discounts", "type": "boolean", "description": "The option to determine whether pricing rule-based\ndiscounts are automatically applied to an order.", "readOnly": false, "required": false }, { "name": "auto_apply_taxes", "type": "boolean", "description": "The option to determine whether rule-based taxes are automatically\napplied to an order when the criteria of the corresponding rules are met.", "readOnly": false, "required": false } ] }, { "name": "OrderReward", "properties": [ { "name": "id", "type": "string", "description": "The identifier of the reward.", "readOnly": false, "required": true }, { "name": "reward_tier_id", "type": "string", "description": "The identifier of the reward tier corresponding to this reward.", "readOnly": false, "required": true } ] } ], "PayOrderRequest": [ { "name": "PayOrderRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A value you specify that uniquely identifies this request among requests you have sent. If\nyou are unsure whether a particular payment request was completed successfully, you can reattempt\nit with the same idempotency key without worrying about duplicate payments.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).", "readOnly": false, "required": true }, { "name": "order_version", "type": "integer", "description": "The version of the order being paid. If not supplied, the latest version will be paid.", "readOnly": false, "required": false }, { "name": "payment_ids", "type": "array", "description": "The IDs of the [payments](entity:Payment) to collect.\nThe payment total must match the order total.", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the order being paid.", "readOnly": false, "required": true } ] } ], "ListPaymentsRequest": [ { "name": "ListPaymentsRequest", "properties": [ { "name": "begin_time", "type": "string", "description": "Indicates the start of the time range to retrieve payments for, in RFC 3339 format. \nThe range is determined using the `created_at` field for each Payment.\nInclusive. Default: The current time minus one year.", "readOnly": false, "required": false }, { "name": "end_time", "type": "string", "description": "Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The \nrange is determined using the `created_at` field for each Payment.\n\nDefault: The current time.", "readOnly": false, "required": false }, { "name": "sort_order", "type": "string", "description": "The order in which results are listed by `ListPaymentsRequest.sort_field`:\n- `ASC` - Oldest to newest.\n- `DESC` - Newest to oldest (default).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "Limit results to the location supplied. By default, results are returned\nfor the default (main) location associated with the seller.", "readOnly": false, "required": false }, { "name": "total", "type": "integer", "description": "The exact amount in the `total_money` for a payment.", "readOnly": false, "required": false }, { "name": "last_4", "type": "string", "description": "The last four digits of a payment card.", "readOnly": false, "required": false }, { "name": "card_brand", "type": "string", "description": "The brand of the payment card (for example, VISA).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to be returned in a single page.\nIt is possible to receive fewer results than the specified limit on a given page.\n\nThe default value of 100 is also the maximum allowed value. If the provided value is \ngreater than 100, it is ignored and the default value is used instead.\n\nDefault: `100`", "readOnly": false, "required": false }, { "name": "is_offline_payment", "type": "boolean", "description": "Whether the payment was taken offline or not.", "readOnly": false, "required": false }, { "name": "offline_begin_time", "type": "string", "description": "Indicates the start of the time range for which to retrieve offline payments, in RFC 3339\nformat for timestamps. The range is determined using the\n`offline_payment_details.client_created_at` field for each Payment. If set, payments without a\nvalue set in `offline_payment_details.client_created_at` will not be returned.\n\nDefault: The current time.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "offline_end_time", "type": "string", "description": "Indicates the end of the time range for which to retrieve offline payments, in RFC 3339\nformat for timestamps. The range is determined using the\n`offline_payment_details.client_created_at` field for each Payment. If set, payments without a\nvalue set in `offline_payment_details.client_created_at` will not be returned.\n\nDefault: The current time.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "updated_at_begin_time", "type": "string", "description": "Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The\nrange is determined using the `updated_at` field for each Payment.", "readOnly": false, "required": false }, { "name": "updated_at_end_time", "type": "string", "description": "Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The\nrange is determined using the `updated_at` field for each Payment.", "readOnly": false, "required": false }, { "name": "sort_field", "type": "#/components/schemas/ListPaymentsRequestSortField", "description": "The field used to sort results by. The default is `CREATED_AT`.\n", "readOnly": false, "required": false } ] }, { "name": "ListPaymentsRequestSortField", "properties": [] } ], "CreatePaymentRequest": [ { "name": "CreatePaymentRequest", "properties": [ { "name": "source_id", "type": "string", "description": "The ID for the source of funds for this payment.\nThis could be a payment token generated by the Web Payments SDK for any of its\n[supported methods](https://developer.squareup.com/docs/web-payments/overview#explore-payment-methods),\nincluding cards, bank transfers, Afterpay or Cash App Pay. If recording a payment\nthat the seller received outside of Square, specify either \"CASH\" or \"EXTERNAL\".\nFor more information, see \n[Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `CreatePayment` request. Keys can be any valid string\nbut must be unique for every `CreatePayment` request.\n\nNote: The number of allowed characters might be less than the stated maximum, if multi-byte\ncharacters are used.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).", "readOnly": false, "required": true }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money to accept for this payment, not including `tip_money`.\n\nThe amount must be specified in the smallest denomination of the applicable currency\n(for example, US dollar amounts are specified in cents). For more information, see\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).\n\nThe currency code must match the currency associated with the business\nthat is accepting the payment.", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The amount designated as a tip, in addition to `amount_money`.\n\nThe amount must be specified in the smallest denomination of the applicable currency\n(for example, US dollar amounts are specified in cents). For more information, see\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).\n\nThe currency code must match the currency associated with the business\nthat is accepting the payment.", "readOnly": false, "required": false }, { "name": "app_fee_money", "type": "#/components/schemas/Money", "description": "The amount of money that the developer is taking as a fee\nfor facilitating the payment on behalf of the seller.\n\nThe amount cannot be more than 90% of the total amount of the payment.\n\nThe amount must be specified in the smallest denomination of the applicable currency\n(for example, US dollar amounts are specified in cents). For more information, see\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).\n\nThe fee currency code must match the currency associated with the seller\nthat is accepting the payment. The application must be from a developer\naccount in the same country and using the same currency code as the seller.\n\nFor more information about the application fee scenario, see\n[Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).\n\nTo set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required.\nFor more information, see [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).", "readOnly": false, "required": false }, { "name": "delay_duration", "type": "string", "description": "The duration of time after the payment's creation when Square automatically \neither completes or cancels the payment depending on the `delay_action` field value. \nFor more information, see \n[Time threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). \n\nThis parameter should be specified as a time duration, in RFC 3339 format.\n\nNote: This feature is only supported for card payments. This parameter can only be set for a delayed\ncapture payment (`autocomplete=false`).\n\nDefault:\n\n- Card-present payments: \"PT36H\" (36 hours) from the creation time.\n- Card-not-present payments: \"P7D\" (7 days) from the creation time.\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "delay_action", "type": "string", "description": "The action to be applied to the payment when the `delay_duration` has elapsed. The action must be\nCANCEL or COMPLETE. For more information, see \n[Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). \n\nDefault: CANCEL", "readOnly": false, "required": false }, { "name": "autocomplete", "type": "boolean", "description": "If set to `true`, this payment will be completed when possible. If\nset to `false`, this payment is held in an approved state until either\nexplicitly completed (captured) or canceled (voided). For more information, see\n[Delayed capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment).\n\nDefault: true", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "Associates a previously created order with this payment.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The [Customer](entity:Customer) ID of the customer associated with the payment.\n\nThis is required if the `source_id` refers to a card on file created using the Cards API.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The location ID to associate with the payment. If not specified, the [main location](https://developer.squareup.com/docs/locations-api#about-the-main-location) is\nused.", "readOnly": false, "required": false }, { "name": "team_member_id", "type": "string", "description": "An optional [TeamMember](entity:TeamMember) ID to associate with \nthis payment.", "readOnly": false, "required": false }, { "name": "reference_id", "type": "string", "description": "A user-defined ID to associate with the payment.\n\nYou can use this field to associate the payment to an entity in an external system \n(for example, you might specify an order ID that is generated by a third-party shopping cart).", "readOnly": false, "required": false }, { "name": "verification_token", "type": "string", "description": "An identifying token generated by [payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).\nVerification tokens encapsulate customer device information and 3-D Secure\nchallenge results to indicate that Square has verified the buyer identity.\n\nFor more information, see [SCA Overview](https://developer.squareup.com/docs/sca-overview).", "readOnly": false, "required": false }, { "name": "accept_partial_authorization", "type": "boolean", "description": "If set to `true` and charging a Square Gift Card, a payment might be returned with\n`amount_money` equal to less than what was requested. For example, a request for $20 when charging\na Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose\nto prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card\npayment. This field cannot be `true` when `autocomplete = true`.\n\nFor more information, see\n[Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).\n\nDefault: false", "readOnly": false, "required": false }, { "name": "buyer_email_address", "type": "string", "description": "The buyer's email address.", "readOnly": false, "required": false }, { "name": "buyer_phone_number", "type": "string", "description": "The buyer's phone number.\nMust follow the following format:\n1. A leading + symbol (followed by a country code)\n2. The phone number can contain spaces and the special characters `(` , `)` , `-` , and `.`.\nAlphabetical characters aren't allowed.\n3. The phone number must contain between 9 and 16 digits.", "readOnly": false, "required": false }, { "name": "billing_address", "type": "#/components/schemas/Address", "description": "The buyer's billing address.", "readOnly": false, "required": false }, { "name": "shipping_address", "type": "#/components/schemas/Address", "description": "The buyer's shipping address.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "An optional note to be entered by the developer when creating a payment.", "readOnly": false, "required": false }, { "name": "statement_description_identifier", "type": "string", "description": "Optional additional payment information to include on the customer's card statement\nas part of the statement description. This can be, for example, an invoice number, ticket number,\nor short description that uniquely identifies the purchase.\n\nNote that the `statement_description_identifier` might get truncated on the statement description\nto fit the required information including the Square identifier (SQ *) and name of the\nseller taking the payment.", "readOnly": false, "required": false }, { "name": "cash_details", "type": "#/components/schemas/CashPaymentDetails", "description": "Additional details required when recording a cash payment (`source_id` is CASH).", "readOnly": false, "required": false }, { "name": "external_details", "type": "#/components/schemas/ExternalPaymentDetails", "description": "Additional details required when recording an external payment (`source_id` is EXTERNAL).", "readOnly": false, "required": false }, { "name": "customer_details", "type": "#/components/schemas/CustomerDetails", "description": "Details about the customer making the payment.", "readOnly": false, "required": false }, { "name": "offline_payment_details", "type": "#/components/schemas/OfflinePaymentDetails", "description": "An optional field for specifying the offline payment details. This is intended for\ninternal 1st-party callers only.", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "CashPaymentDetails", "properties": [ { "name": "buyer_supplied_money", "type": "#/components/schemas/Money", "description": "The amount and currency of the money supplied by the buyer.", "readOnly": false, "required": true }, { "name": "change_back_money", "type": "#/components/schemas/Money", "description": "The amount of change due back to the buyer. \nThis read-only field is calculated\nfrom the `amount_money` and `buyer_supplied_money` fields.", "readOnly": false, "required": false } ] }, { "name": "ExternalPaymentDetails", "properties": [ { "name": "type", "type": "string", "description": "The type of external payment the seller received. It can be one of the following:\n- CHECK - Paid using a physical check.\n- BANK_TRANSFER - Paid using external bank transfer.\n- OTHER\\_GIFT\\_CARD - Paid using a non-Square gift card.\n- CRYPTO - Paid using a crypto currency.\n- SQUARE_CASH - Paid using Square Cash App.\n- SOCIAL - Paid using peer-to-peer payment applications.\n- EXTERNAL - A third-party application gathered this payment outside of Square.\n- EMONEY - Paid using an E-money provider.\n- CARD - A credit or debit card that Square does not support.\n- STORED_BALANCE - Use for house accounts, store credit, and so forth.\n- FOOD_VOUCHER - Restaurant voucher provided by employers to employees to pay for meals\n- OTHER - A type not listed here.", "readOnly": false, "required": true }, { "name": "source", "type": "string", "description": "A description of the external payment source. For example, \n\"Food Delivery Service\".", "readOnly": false, "required": true }, { "name": "source_id", "type": "string", "description": "An ID to associate the payment to its originating source.", "readOnly": false, "required": false }, { "name": "source_fee_money", "type": "#/components/schemas/Money", "description": "The fees paid to the source. The `amount_money` minus this field is \nthe net amount seller receives.", "readOnly": false, "required": false } ] }, { "name": "CustomerDetails", "properties": [ { "name": "customer_initiated", "type": "boolean", "description": "Indicates whether the customer initiated the payment.", "readOnly": false, "required": false }, { "name": "seller_keyed_in", "type": "boolean", "description": "Indicates that the seller keyed in payment details on behalf of the customer.\nThis is used to flag a payment as Mail Order / Telephone Order (MOTO).", "readOnly": false, "required": false } ] }, { "name": "OfflinePaymentDetails", "properties": [ { "name": "client_created_at", "type": "string", "description": "The client-side timestamp of when the offline payment was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "CancelPaymentByIdempotencyKeyRequest": [ { "name": "CancelPaymentByIdempotencyKeyRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "The `idempotency_key` identifying the payment to be canceled.", "readOnly": false, "required": true } ] } ], "GetPaymentRequest": [ { "name": "GetPaymentRequest", "properties": [ { "name": "payment_id", "type": "string", "description": "A unique ID for the desired payment.", "readOnly": false, "required": true } ] } ], "UpdatePaymentRequest": [ { "name": "UpdatePaymentRequest", "properties": [ { "name": "payment", "type": "#/components/schemas/Payment", "description": "The updated `Payment` object.", "readOnly": false, "required": false }, { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `UpdatePayment` request. Keys can be any valid string\nbut must be unique for every `UpdatePayment` request.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": true }, { "name": "payment_id", "type": "string", "description": "The ID of the payment to update.", "readOnly": false, "required": true } ] }, { "name": "Payment", "properties": [ { "name": "id", "type": "string", "description": "A unique ID for the payment.", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp of when the payment was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp of when the payment was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount processed for this payment, not including `tip_money`.\n\nThe amount is specified in the smallest denomination of the applicable currency (for example,\nUS dollar amounts are specified in cents). For more information, see\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The amount designated as a tip. \n\nThis amount is specified in the smallest denomination of the applicable currency (for example,\nUS dollar amounts are specified in cents). For more information, see\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).", "readOnly": false, "required": false }, { "name": "total_money", "type": "#/components/schemas/Money", "description": "The total amount for the payment, including `amount_money` and `tip_money`.\nThis amount is specified in the smallest denomination of the applicable currency (for example,\nUS dollar amounts are specified in cents). For more information, see\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).", "readOnly": true, "required": false }, { "name": "app_fee_money", "type": "#/components/schemas/Money", "description": "The amount the developer is taking as a fee for facilitating the payment on behalf\nof the seller. This amount is specified in the smallest denomination of the applicable currency\n(for example, US dollar amounts are specified in cents). For more information,\nsee [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).\n\nThe amount cannot be more than 90% of the `total_money` value.\n\nTo set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required.\nFor more information, see [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).", "readOnly": false, "required": false }, { "name": "approved_money", "type": "#/components/schemas/Money", "description": "The amount of money approved for this payment. This value may change if Square chooses to\nobtain reauthorization as part of a call to [UpdatePayment](api-endpoint:Payments-UpdatePayment).", "readOnly": false, "required": false }, { "name": "processing_fee", "type": "array", "description": "The processing fees and fee adjustments assessed by Square for this payment.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/ProcessingFee" }, { "name": "refunded_money", "type": "#/components/schemas/Money", "description": "The total amount of the payment refunded to date. \n\nThis amount is specified in the smallest denomination of the applicable currency (for example,\nUS dollar amounts are specified in cents).", "readOnly": true, "required": false }, { "name": "status", "type": "string", "description": "Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED.", "readOnly": true, "required": false }, { "name": "delay_duration", "type": "string", "description": "The duration of time after the payment's creation when Square automatically applies the\n`delay_action` to the payment. This automatic `delay_action` applies only to payments that\ndo not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the `delay_duration`\ntime period.\n\nThis field is specified as a time duration, in RFC 3339 format.\n\nNotes:\nThis feature is only supported for card payments.\n\nDefault:\n\n- Card-present payments: \"PT36H\" (36 hours) from the creation time.\n- Card-not-present payments: \"P7D\" (7 days) from the creation time.\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": true, "required": false }, { "name": "delay_action", "type": "string", "description": "The action to be applied to the payment when the `delay_duration` has elapsed.\n\nCurrent values include `CANCEL` and `COMPLETE`.", "readOnly": false, "required": false }, { "name": "delayed_until", "type": "string", "description": "The read-only timestamp of when the `delay_action` is automatically applied,\nin RFC 3339 format.\n\nNote that this field is calculated by summing the payment's `delay_duration` and `created_at`\nfields. The `created_at` field is generated by Square and might not exactly match the\ntime on your local machine.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "source_type", "type": "string", "description": "The source type for this payment.\n\nCurrent values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `BUY_NOW_PAY_LATER`, `SQUARE_ACCOUNT`,\n`CASH` and `EXTERNAL`. For information about these payment source types,\nsee [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).", "readOnly": true, "required": false }, { "name": "card_details", "type": "#/components/schemas/CardPaymentDetails", "description": "Details about a card payment. These details are only populated if the source_type is `CARD`.", "readOnly": true, "required": false }, { "name": "cash_details", "type": "#/components/schemas/CashPaymentDetails", "description": "Details about a cash payment. These details are only populated if the source_type is `CASH`.", "readOnly": false, "required": false }, { "name": "bank_account_details", "type": "#/components/schemas/BankAccountPaymentDetails", "description": "Details about a bank account payment. These details are only populated if the source_type is `BANK_ACCOUNT`.", "readOnly": true, "required": false }, { "name": "external_details", "type": "#/components/schemas/ExternalPaymentDetails", "description": "Details about an external payment. The details are only populated \nif the `source_type` is `EXTERNAL`.", "readOnly": true, "required": false }, { "name": "wallet_details", "type": "#/components/schemas/DigitalWalletDetails", "description": "Details about an wallet payment. The details are only populated \nif the `source_type` is `WALLET`.", "readOnly": true, "required": false }, { "name": "buy_now_pay_later_details", "type": "#/components/schemas/BuyNowPayLaterDetails", "description": "Details about a Buy Now Pay Later payment. The details are only populated\nif the `source_type` is `BUY_NOW_PAY_LATER`. For more information, see \n[Afterpay Payments](https://developer.squareup.com/docs/payments-api/take-payments/afterpay-payments).", "readOnly": true, "required": false }, { "name": "square_account_details", "type": "#/components/schemas/SquareAccountDetails", "description": "Details about a Square Account payment. The details are only populated\nif the `source_type` is `SQUARE_ACCOUNT`.", "readOnly": true, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the location associated with the payment.", "readOnly": true, "required": false }, { "name": "order_id", "type": "string", "description": "The ID of the order associated with the payment.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional ID that associates the payment with an entity in\nanother system.", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the customer associated with the payment. If the ID is \nnot provided in the `CreatePayment` request that was used to create the `Payment`, \nSquare may use information in the request \n(such as the billing and shipping address, email address, and payment source) \nto identify a matching customer profile in the Customer Directory. \nIf found, the profile ID is used. If a profile is not found, the \nAPI attempts to create an \n[instant profile](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles). \nIf the API cannot create an \ninstant profile (either because the seller has disabled it or the \nseller's region prevents creating it), this field remains unset. Note that \nthis process is asynchronous and it may take some time before a \ncustomer ID is added to the payment.", "readOnly": true, "required": false }, { "name": "employee_id", "type": "string", "description": "__Deprecated__: Use `Payment.team_member_id` instead.\n\nAn optional ID of the employee associated with taking the payment.", "readOnly": true, "required": false }, { "name": "team_member_id", "type": "string", "description": "An optional ID of the [TeamMember](entity:TeamMember) associated with taking the payment.", "readOnly": false, "required": false }, { "name": "refund_ids", "type": "array", "description": "A list of `refund_id`s identifying refunds for the payment.", "readOnly": true, "required": false }, { "name": "risk_evaluation", "type": "#/components/schemas/RiskEvaluation", "description": "Provides information about the risk associated with the payment, as determined by Square.\nThis field is present for payments to sellers that have opted in to receive risk\nevaluations.", "readOnly": true, "required": false }, { "name": "terminal_checkout_id", "type": "string", "description": "An optional ID for a Terminal checkout that is associated with the payment.", "readOnly": true, "required": false }, { "name": "buyer_email_address", "type": "string", "description": "The buyer's email address.", "readOnly": true, "required": false }, { "name": "billing_address", "type": "#/components/schemas/Address", "description": "The buyer's billing address.", "readOnly": true, "required": false }, { "name": "shipping_address", "type": "#/components/schemas/Address", "description": "The buyer's shipping address.", "readOnly": true, "required": false }, { "name": "note", "type": "string", "description": "An optional note to include when creating a payment.", "readOnly": true, "required": false }, { "name": "statement_description_identifier", "type": "string", "description": "Additional payment information that gets added to the customer's card statement\nas part of the statement description.\n\nNote that the `statement_description_identifier` might get truncated on the statement description\nto fit the required information including the Square identifier (SQ *) and the name of the\nseller taking the payment.", "readOnly": true, "required": false }, { "name": "capabilities", "type": "array", "description": "Actions that can be performed on this payment:\n- `EDIT_AMOUNT_UP` - The payment amount can be edited up.\n- `EDIT_AMOUNT_DOWN` - The payment amount can be edited down.\n- `EDIT_TIP_AMOUNT_UP` - The tip amount can be edited up.\n- `EDIT_TIP_AMOUNT_DOWN` - The tip amount can be edited down.\n- `EDIT_DELAY_ACTION` - The delay_action can be edited.", "readOnly": true, "required": false }, { "name": "receipt_number", "type": "string", "description": "The payment's receipt number.\nThe field is missing if a payment is canceled.", "readOnly": true, "required": false }, { "name": "receipt_url", "type": "string", "description": "The URL for the payment's receipt.\nThe field is only populated for COMPLETED payments.", "readOnly": true, "required": false }, { "name": "device_details", "type": "#/components/schemas/DeviceDetails", "description": "Details about the device that took the payment.", "readOnly": true, "required": false }, { "name": "application_details", "type": "#/components/schemas/ApplicationDetails", "description": "Details about the application that took the payment.", "readOnly": true, "required": false }, { "name": "is_offline_payment", "type": "boolean", "description": "Whether or not this payment was taken offline.", "readOnly": true, "required": false }, { "name": "offline_payment_details", "type": "#/components/schemas/OfflinePaymentDetails", "description": "Additional information about the payment if it was taken offline.", "readOnly": true, "required": false }, { "name": "version_token", "type": "string", "description": "Used for optimistic concurrency. This opaque token identifies a specific version of the\n`Payment` object.", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "ProcessingFee", "properties": [ { "name": "effective_at", "type": "string", "description": "The timestamp of when the fee takes effect, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "type", "type": "string", "description": "The type of fee assessed or adjusted. The fee type can be `INITIAL` or `ADJUSTMENT`.", "readOnly": false, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The fee amount, which might be negative, that is assessed or adjusted by Square.\n\nPositive values represent funds being assessed, while negative values represent\nfunds being returned.", "readOnly": false, "required": false } ] }, { "name": "CardPaymentDetails", "properties": [ { "name": "status", "type": "string", "description": "The card payment's current state. The state can be AUTHORIZED, CAPTURED, VOIDED, or\nFAILED.", "readOnly": false, "required": false }, { "name": "card", "type": "#/components/schemas/Card", "description": "The credit card's non-confidential details.", "readOnly": false, "required": false }, { "name": "entry_method", "type": "string", "description": "The method used to enter the card's details for the payment. The method can be\n`KEYED`, `SWIPED`, `EMV`, `ON_FILE`, or `CONTACTLESS`.", "readOnly": false, "required": false }, { "name": "cvv_status", "type": "string", "description": "The status code returned from the Card Verification Value (CVV) check. The code can be\n`CVV_ACCEPTED`, `CVV_REJECTED`, or `CVV_NOT_CHECKED`.", "readOnly": false, "required": false }, { "name": "avs_status", "type": "string", "description": "The status code returned from the Address Verification System (AVS) check. The code can be\n`AVS_ACCEPTED`, `AVS_REJECTED`, or `AVS_NOT_CHECKED`.", "readOnly": false, "required": false }, { "name": "auth_result_code", "type": "string", "description": "The status code returned by the card issuer that describes the payment's\nauthorization status.", "readOnly": false, "required": false }, { "name": "application_identifier", "type": "string", "description": "For EMV payments, the application ID identifies the EMV application used for the payment.", "readOnly": false, "required": false }, { "name": "application_name", "type": "string", "description": "For EMV payments, the human-readable name of the EMV application used for the payment.", "readOnly": false, "required": false }, { "name": "application_cryptogram", "type": "string", "description": "For EMV payments, the cryptogram generated for the payment.", "readOnly": false, "required": false }, { "name": "verification_method", "type": "string", "description": "For EMV payments, the method used to verify the cardholder's identity. The method can be\n`PIN`, `SIGNATURE`, `PIN_AND_SIGNATURE`, `ON_DEVICE`, or `NONE`.", "readOnly": false, "required": false }, { "name": "verification_results", "type": "string", "description": "For EMV payments, the results of the cardholder verification. The result can be\n`SUCCESS`, `FAILURE`, or `UNKNOWN`.", "readOnly": false, "required": false }, { "name": "statement_description", "type": "string", "description": "The statement description sent to the card networks.\n\nNote: The actual statement description varies and is likely to be truncated and appended with\nadditional information on a per issuer basis.", "readOnly": false, "required": false }, { "name": "device_details", "type": "#/components/schemas/DeviceDetails", "description": "__Deprecated__: Use `Payment.device_details` instead.\n\nDetails about the device that took the payment.", "readOnly": false, "required": false }, { "name": "card_payment_timeline", "type": "#/components/schemas/CardPaymentTimeline", "description": "The timeline for card payments.", "readOnly": false, "required": false }, { "name": "refund_requires_card_presence", "type": "boolean", "description": "Whether the card must be physically present for the payment to\nbe refunded. If set to `true`, the card must be present.", "readOnly": false, "required": false }, { "name": "errors", "type": "array", "description": "Information about errors encountered during the request.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Error" } ] }, { "name": "Card", "properties": [ { "name": "id", "type": "string", "description": "Unique ID for this card. Generated by Square.", "readOnly": true, "required": false }, { "name": "card_brand", "type": "#/components/schemas/CardBrand", "description": "The card's brand.\n", "readOnly": true, "required": false }, { "name": "last_4", "type": "string", "description": "The last 4 digits of the card number.", "readOnly": true, "required": false }, { "name": "exp_month", "type": "integer", "description": "The expiration month of the associated card as an integer between 1 and 12.", "readOnly": false, "required": false }, { "name": "exp_year", "type": "integer", "description": "The four-digit year of the card's expiration date.", "readOnly": false, "required": false }, { "name": "cardholder_name", "type": "string", "description": "The name of the cardholder.", "readOnly": false, "required": false }, { "name": "billing_address", "type": "#/components/schemas/Address", "description": "The billing address for this card.", "readOnly": false, "required": false }, { "name": "fingerprint", "type": "string", "description": "Intended as a Square-assigned identifier, based\non the card number, to identify the card across multiple locations within a\nsingle application.", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "**Required** The ID of a customer created using the Customers API to be associated with the card.", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the merchant associated with the card.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional user-defined reference ID that associates this card with\nanother entity in an external system. For example, a customer ID from an\nexternal customer management system.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "Indicates whether or not a card can be used for payments.", "readOnly": true, "required": false }, { "name": "card_type", "type": "#/components/schemas/CardType", "description": "The type of the card.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "prepaid_type", "type": "#/components/schemas/CardPrepaidType", "description": "Indicates whether the Card is prepaid or not.\nThe Card object includes this field only in response to Payments API calls.\n", "readOnly": true, "required": false }, { "name": "bin", "type": "string", "description": "The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API\nreturns this field.", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "Current version number of the card. Increments with each card update. Requests to update an\nexisting Card object will be rejected unless the version in the request matches the current\nversion for the Card.", "readOnly": false, "required": false }, { "name": "card_co_brand", "type": "#/components/schemas/CardCoBrand", "description": "The card's co-brand if available. For example, an Afterpay virtual card would have a\nco-brand of AFTERPAY.\n", "readOnly": true, "required": false } ] }, { "name": "CardBrand", "properties": [] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "CardType", "properties": [] }, { "name": "CardPrepaidType", "properties": [] }, { "name": "CardCoBrand", "properties": [] }, { "name": "DeviceDetails", "properties": [ { "name": "device_id", "type": "string", "description": "The Square-issued ID of the device.", "readOnly": false, "required": false }, { "name": "device_installation_id", "type": "string", "description": "The Square-issued installation ID for the device.", "readOnly": false, "required": false }, { "name": "device_name", "type": "string", "description": "The name of the device set by the seller.", "readOnly": false, "required": false } ] }, { "name": "CardPaymentTimeline", "properties": [ { "name": "authorized_at", "type": "string", "description": "The timestamp when the payment was authorized, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "captured_at", "type": "string", "description": "The timestamp when the payment was captured, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "voided_at", "type": "string", "description": "The timestamp when the payment was voided, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false } ] }, { "name": "Error", "properties": [ { "name": "category", "type": "#/components/schemas/ErrorCategory", "description": "The high-level category for the error.\n", "readOnly": false, "required": true }, { "name": "code", "type": "#/components/schemas/ErrorCode", "description": "The specific code of the error.\n", "readOnly": false, "required": true }, { "name": "detail", "type": "string", "description": "A human-readable description of the error for debugging purposes.", "readOnly": false, "required": false }, { "name": "field", "type": "string", "description": "The name of the field provided in the original request (if any) that\nthe error pertains to.", "readOnly": false, "required": false } ] }, { "name": "ErrorCategory", "properties": [] }, { "name": "ErrorCode", "properties": [] }, { "name": "CashPaymentDetails", "properties": [ { "name": "buyer_supplied_money", "type": "#/components/schemas/Money", "description": "The amount and currency of the money supplied by the buyer.", "readOnly": false, "required": true }, { "name": "change_back_money", "type": "#/components/schemas/Money", "description": "The amount of change due back to the buyer. \nThis read-only field is calculated\nfrom the `amount_money` and `buyer_supplied_money` fields.", "readOnly": false, "required": false } ] }, { "name": "BankAccountPaymentDetails", "properties": [ { "name": "bank_name", "type": "string", "description": "The name of the bank associated with the bank account.", "readOnly": false, "required": false }, { "name": "transfer_type", "type": "string", "description": "The type of the bank transfer. The type can be `ACH` or `UNKNOWN`.", "readOnly": false, "required": false }, { "name": "account_ownership_type", "type": "string", "description": "The ownership type of the bank account performing the transfer.\nThe type can be `INDIVIDUAL`, `COMPANY`, or `ACCOUNT_TYPE_UNKNOWN`.", "readOnly": false, "required": false }, { "name": "fingerprint", "type": "string", "description": "Uniquely identifies the bank account for this seller and can be used\nto determine if payments are from the same bank account.", "readOnly": false, "required": false }, { "name": "country", "type": "string", "description": "The two-letter ISO code representing the country the bank account is located in.", "readOnly": false, "required": false }, { "name": "statement_description", "type": "string", "description": "The statement description as sent to the bank.", "readOnly": false, "required": false }, { "name": "ach_details", "type": "#/components/schemas/ACHDetails", "description": "ACH-specific information about the transfer. The information is only populated\nif the `transfer_type` is `ACH`.", "readOnly": false, "required": false }, { "name": "errors", "type": "array", "description": "Information about errors encountered during the request.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Error" } ] }, { "name": "ACHDetails", "properties": [ { "name": "routing_number", "type": "string", "description": "The routing number for the bank account.", "readOnly": false, "required": false }, { "name": "account_number_suffix", "type": "string", "description": "The last few digits of the bank account number.", "readOnly": false, "required": false }, { "name": "account_type", "type": "string", "description": "The type of the bank account performing the transfer. The account type can be `CHECKING`,\n`SAVINGS`, or `UNKNOWN`.", "readOnly": false, "required": false } ] }, { "name": "ExternalPaymentDetails", "properties": [ { "name": "type", "type": "string", "description": "The type of external payment the seller received. It can be one of the following:\n- CHECK - Paid using a physical check.\n- BANK_TRANSFER - Paid using external bank transfer.\n- OTHER\\_GIFT\\_CARD - Paid using a non-Square gift card.\n- CRYPTO - Paid using a crypto currency.\n- SQUARE_CASH - Paid using Square Cash App.\n- SOCIAL - Paid using peer-to-peer payment applications.\n- EXTERNAL - A third-party application gathered this payment outside of Square.\n- EMONEY - Paid using an E-money provider.\n- CARD - A credit or debit card that Square does not support.\n- STORED_BALANCE - Use for house accounts, store credit, and so forth.\n- FOOD_VOUCHER - Restaurant voucher provided by employers to employees to pay for meals\n- OTHER - A type not listed here.", "readOnly": false, "required": true }, { "name": "source", "type": "string", "description": "A description of the external payment source. For example, \n\"Food Delivery Service\".", "readOnly": false, "required": true }, { "name": "source_id", "type": "string", "description": "An ID to associate the payment to its originating source.", "readOnly": false, "required": false }, { "name": "source_fee_money", "type": "#/components/schemas/Money", "description": "The fees paid to the source. The `amount_money` minus this field is \nthe net amount seller receives.", "readOnly": false, "required": false } ] }, { "name": "DigitalWalletDetails", "properties": [ { "name": "status", "type": "string", "description": "The status of the `WALLET` payment. The status can be `AUTHORIZED`, `CAPTURED`, `VOIDED`, or\n`FAILED`.", "readOnly": false, "required": false }, { "name": "brand", "type": "string", "description": "The brand used for the `WALLET` payment. The brand can be `CASH_APP`, `PAYPAY`, `ALIPAY`,\n`RAKUTEN_PAY`, `AU_PAY`, `D_BARAI`, `MERPAY`, `WECHAT_PAY` or `UNKNOWN`.", "readOnly": false, "required": false }, { "name": "cash_app_details", "type": "#/components/schemas/CashAppDetails", "description": "Brand-specific details for payments with the `brand` of `CASH_APP`.", "readOnly": false, "required": false } ] }, { "name": "CashAppDetails", "properties": [ { "name": "buyer_full_name", "type": "string", "description": "The name of the Cash App account holder.", "readOnly": false, "required": false }, { "name": "buyer_country_code", "type": "string", "description": "The country of the Cash App account holder, in ISO 3166-1-alpha-2 format.\n\nFor possible values, see [Country](entity:Country).", "readOnly": false, "required": false }, { "name": "buyer_cashtag", "type": "string", "description": "$Cashtag of the Cash App account holder.", "readOnly": true, "required": false } ] }, { "name": "BuyNowPayLaterDetails", "properties": [ { "name": "brand", "type": "string", "description": "The brand used for the Buy Now Pay Later payment.\nThe brand can be `AFTERPAY`, `CLEARPAY` or `UNKNOWN`.", "readOnly": false, "required": false }, { "name": "afterpay_details", "type": "#/components/schemas/AfterpayDetails", "description": "Details about an Afterpay payment. These details are only populated if the `brand` is\n`AFTERPAY`.", "readOnly": false, "required": false }, { "name": "clearpay_details", "type": "#/components/schemas/ClearpayDetails", "description": "Details about a Clearpay payment. These details are only populated if the `brand` is\n`CLEARPAY`.", "readOnly": false, "required": false } ] }, { "name": "AfterpayDetails", "properties": [ { "name": "email_address", "type": "string", "description": "Email address on the buyer's Afterpay account.", "readOnly": false, "required": false } ] }, { "name": "ClearpayDetails", "properties": [ { "name": "email_address", "type": "string", "description": "Email address on the buyer's Clearpay account.", "readOnly": false, "required": false } ] }, { "name": "SquareAccountDetails", "properties": [ { "name": "payment_source_token", "type": "string", "description": "Unique identifier for the payment source used for this payment.", "readOnly": false, "required": false }, { "name": "errors", "type": "array", "description": "Information about errors encountered during the request.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Error" } ] }, { "name": "RiskEvaluation", "properties": [ { "name": "created_at", "type": "string", "description": "The timestamp when payment risk was evaluated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "risk_level", "type": "#/components/schemas/RiskEvaluationRiskLevel", "description": "The risk level associated with the payment\n", "readOnly": false, "required": false } ] }, { "name": "RiskEvaluationRiskLevel", "properties": [] }, { "name": "ApplicationDetails", "properties": [ { "name": "square_product", "type": "#/components/schemas/ApplicationDetailsExternalSquareProduct", "description": "The Square product, such as Square Point of Sale (POS), \nSquare Invoices, or Square Virtual Terminal.\n", "readOnly": false, "required": false }, { "name": "application_id", "type": "string", "description": "The Square ID assigned to the application used to take the payment. \nApplication developers can use this information to identify payments that \ntheir application processed. \nFor example, if a developer uses a custom application to process payments, \nthis field contains the application ID from the Developer Dashboard. \nIf a seller uses a [Square App Marketplace](https://developer.squareup.com/docs/app-marketplace) \napplication to process payments, the field contains the corresponding application ID.", "readOnly": false, "required": false } ] }, { "name": "ApplicationDetailsExternalSquareProduct", "properties": [] }, { "name": "OfflinePaymentDetails", "properties": [ { "name": "client_created_at", "type": "string", "description": "The client-side timestamp of when the offline payment was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "CancelPaymentRequest": [ { "name": "CancelPaymentRequest", "properties": [ { "name": "payment_id", "type": "string", "description": "The ID of the payment to cancel.", "readOnly": false, "required": true } ] } ], "CompletePaymentRequest": [ { "name": "CompletePaymentRequest", "properties": [ { "name": "version_token", "type": "string", "description": "Used for optimistic concurrency. This opaque token identifies the current `Payment` \nversion that the caller expects. If the server has a different version of the Payment, \nthe update fails and a response with a VERSION_MISMATCH error is returned.", "readOnly": false, "required": false }, { "name": "payment_id", "type": "string", "description": "The unique ID identifying the payment to be completed.", "readOnly": false, "required": true } ] } ], "ListPayoutsRequest": [ { "name": "ListPayoutsRequest", "properties": [ { "name": "location_id", "type": "string", "description": "The ID of the location for which to list the payouts.\nBy default, payouts are returned for the default (main) location associated with the seller.", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/PayoutStatus", "description": "If provided, only payouts with the given status are returned.", "readOnly": false, "required": false }, { "name": "begin_time", "type": "string", "description": "The timestamp for the beginning of the payout creation time, in RFC 3339 format.\nInclusive. Default: The current time minus one year.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "end_time", "type": "string", "description": "The timestamp for the end of the payout creation time, in RFC 3339 format.\nDefault: The current time.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "The order in which payouts are listed.\n", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).\nIf request parameters change between requests, subsequent results may contain duplicates or missing records.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to be returned in a single page.\nIt is possible to receive fewer results than the specified limit on a given page.\nThe default value of 100 is also the maximum allowed value. If the provided value is\ngreater than 100, it is ignored and the default value is used instead.\nDefault: `100`", "readOnly": false, "required": false } ] }, { "name": "PayoutStatus", "properties": [] }, { "name": "SortOrder", "properties": [] } ], "GetPayoutRequest": [ { "name": "GetPayoutRequest", "properties": [ { "name": "payout_id", "type": "string", "description": "The ID of the payout to retrieve the information for.", "readOnly": false, "required": true } ] } ], "ListPayoutEntriesRequest": [ { "name": "ListPayoutEntriesRequest", "properties": [ { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "The order in which payout entries are listed.\n", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).\nIf request parameters change between requests, subsequent results may contain duplicates or missing records.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to be returned in a single page.\nIt is possible to receive fewer results than the specified limit on a given page.\nThe default value of 100 is also the maximum allowed value. If the provided value is\ngreater than 100, it is ignored and the default value is used instead.\nDefault: `100`", "readOnly": false, "required": false }, { "name": "payout_id", "type": "string", "description": "The ID of the payout to retrieve the information for.", "readOnly": false, "required": true } ] }, { "name": "SortOrder", "properties": [] } ], "ListPaymentRefundsRequest": [ { "name": "ListPaymentRefundsRequest", "properties": [ { "name": "begin_time", "type": "string", "description": "Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339 \nformat. The range is determined using the `created_at` field for each `PaymentRefund`. \n\nDefault: The current time minus one year.", "readOnly": false, "required": false }, { "name": "end_time", "type": "string", "description": "Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339 \nformat. The range is determined using the `created_at` field for each `PaymentRefund`.\n\nDefault: The current time.", "readOnly": false, "required": false }, { "name": "sort_order", "type": "string", "description": "The order in which results are listed by `PaymentRefund.created_at`:\n- `ASC` - Oldest to newest.\n- `DESC` - Newest to oldest (default).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "Limit results to the location supplied. By default, results are returned\nfor all locations associated with the seller.", "readOnly": false, "required": false }, { "name": "status", "type": "string", "description": "If provided, only refunds with the given status are returned.\nFor a list of refund status values, see [PaymentRefund](entity:PaymentRefund).\n\nDefault: If omitted, refunds are returned regardless of their status.", "readOnly": false, "required": false }, { "name": "source_type", "type": "string", "description": "If provided, only returns refunds whose payments have the indicated source type.\nCurrent values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and `EXTERNAL`.\nFor information about these payment source types, see\n[Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).\n\nDefault: If omitted, refunds are returned regardless of the source type.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to be returned in a single page.\n\nIt is possible to receive fewer results than the specified limit on a given page.\n\nIf the supplied value is greater than 100, no more than 100 results are returned.\n\nDefault: 100", "readOnly": false, "required": false }, { "name": "updated_at_begin_time", "type": "string", "description": "Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339\nformat. The range is determined using the `updated_at` field for each `PaymentRefund`.\n\nDefault: If omitted, the time range starts at `begin_time`.", "readOnly": false, "required": false }, { "name": "updated_at_end_time", "type": "string", "description": "Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339\nformat. The range is determined using the `updated_at` field for each `PaymentRefund`.\n\nDefault: The current time.", "readOnly": false, "required": false }, { "name": "sort_field", "type": "#/components/schemas/ListPaymentRefundsRequestSortField", "description": "The field used to sort results by. The default is `CREATED_AT`.\n", "readOnly": false, "required": false } ] }, { "name": "ListPaymentRefundsRequestSortField", "properties": [] } ], "RefundPaymentRequest": [ { "name": "RefundPaymentRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": " A unique string that identifies this `RefundPayment` request. The key can be any valid string\nbut must be unique for every `RefundPayment` request.\n\nKeys are limited to a max of 45 characters - however, the number of allowed characters might be\nless than 45, if multi-byte characters are used.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).", "readOnly": false, "required": true }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money to refund.\n\nThis amount cannot be more than the `total_money` value of the payment minus the total\namount of all previously completed refunds for this payment.\n\nThis amount must be specified in the smallest denomination of the applicable currency\n(for example, US dollar amounts are specified in cents). For more information, see\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).\n\nThe currency code must match the currency associated with the business\nthat is charging the card.", "readOnly": false, "required": true }, { "name": "app_fee_money", "type": "#/components/schemas/Money", "description": "The amount of money the developer contributes to help cover the refunded amount.\nThis amount is specified in the smallest denomination of the applicable currency (for example,\nUS dollar amounts are specified in cents).\n\nThe value cannot be more than the `amount_money`.\n\nYou can specify this parameter in a refund request only if the same parameter was also included\nwhen taking the payment. This is part of the application fee scenario the API supports. For more\ninformation, see [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).\n\nTo set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required.\nFor more information, see [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).", "readOnly": false, "required": false }, { "name": "payment_id", "type": "string", "description": "The unique ID of the payment being refunded.\nRequired when unlinked=false, otherwise must not be set.", "readOnly": false, "required": false }, { "name": "destination_id", "type": "string", "description": "The ID indicating where funds will be refunded to. Required for unlinked refunds. For more\ninformation, see [Process an Unlinked Refund](https://developer.squareup.com/docs/refunds-api/unlinked-refunds).\n\nFor refunds linked to Square payments, `destination_id` is usually omitted; in this case, funds\nwill be returned to the original payment source. The field may be specified in order to request\na cross-method refund to a gift card. For more information,\nsee [Cross-method refunds to gift cards](https://developer.squareup.com/docs/payments-api/refund-payments#cross-method-refunds-to-gift-cards).", "readOnly": false, "required": false }, { "name": "unlinked", "type": "boolean", "description": "Indicates that the refund is not linked to a Square payment.\nIf set to true, `destination_id` and `location_id` must be supplied while `payment_id` must not\nbe provided.", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The location ID associated with the unlinked refund.\nRequired for requests specifying `unlinked=true`.\nOtherwise, if included when `unlinked=false`, will throw an error.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The [Customer](entity:Customer) ID of the customer associated with the refund.\nThis is required if the `destination_id` refers to a card on file created using the Cards\nAPI. Only allowed when `unlinked=true`.", "readOnly": false, "required": false }, { "name": "reason", "type": "string", "description": "A description of the reason for the refund.", "readOnly": false, "required": false }, { "name": "payment_version_token", "type": "string", "description": " Used for optimistic concurrency. This opaque token identifies the current `Payment`\nversion that the caller expects. If the server has a different version of the Payment,\nthe update fails and a response with a VERSION_MISMATCH error is returned.\nIf the versions match, or the field is not provided, the refund proceeds as normal.", "readOnly": false, "required": false }, { "name": "team_member_id", "type": "string", "description": "An optional [TeamMember](entity:TeamMember) ID to associate with this refund.", "readOnly": false, "required": false }, { "name": "cash_details", "type": "#/components/schemas/DestinationDetailsCashRefundDetails", "description": "Additional details required when recording an unlinked cash refund (`destination_id` is CASH).", "readOnly": false, "required": false }, { "name": "external_details", "type": "#/components/schemas/DestinationDetailsExternalRefundDetails", "description": "Additional details required when recording an unlinked external refund\n(`destination_id` is EXTERNAL).", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "DestinationDetailsCashRefundDetails", "properties": [ { "name": "seller_supplied_money", "type": "#/components/schemas/Money", "description": "The amount and currency of the money supplied by the seller.", "readOnly": false, "required": true }, { "name": "change_back_money", "type": "#/components/schemas/Money", "description": "The amount of change due back to the seller.\nThis read-only field is calculated\nfrom the `amount_money` and `seller_supplied_money` fields.", "readOnly": false, "required": false } ] }, { "name": "DestinationDetailsExternalRefundDetails", "properties": [ { "name": "type", "type": "string", "description": "The type of external refund the seller paid to the buyer. It can be one of the\nfollowing:\n- CHECK - Refunded using a physical check.\n- BANK_TRANSFER - Refunded using external bank transfer.\n- OTHER\\_GIFT\\_CARD - Refunded using a non-Square gift card.\n- CRYPTO - Refunded using a crypto currency.\n- SQUARE_CASH - Refunded using Square Cash App.\n- SOCIAL - Refunded using peer-to-peer payment applications.\n- EXTERNAL - A third-party application gathered this refund outside of Square.\n- EMONEY - Refunded using an E-money provider.\n- CARD - A credit or debit card that Square does not support.\n- STORED_BALANCE - Use for house accounts, store credit, and so forth.\n- FOOD_VOUCHER - Restaurant voucher provided by employers to employees to pay for meals\n- OTHER - A type not listed here.", "readOnly": false, "required": true }, { "name": "source", "type": "string", "description": "A description of the external refund source. For example,\n\"Food Delivery Service\".", "readOnly": false, "required": true }, { "name": "source_id", "type": "string", "description": "An ID to associate the refund to its originating source.", "readOnly": false, "required": false } ] } ], "GetPaymentRefundRequest": [ { "name": "GetPaymentRefundRequest", "properties": [ { "name": "refund_id", "type": "string", "description": "The unique ID for the desired `PaymentRefund`.", "readOnly": false, "required": true } ] } ], "ListSitesRequest": [ { "name": "ListSitesRequest", "properties": [] } ], "DeleteSnippetRequest": [ { "name": "DeleteSnippetRequest", "properties": [ { "name": "site_id", "type": "string", "description": "The ID of the site that contains the snippet.", "readOnly": false, "required": true } ] } ], "RetrieveSnippetRequest": [ { "name": "RetrieveSnippetRequest", "properties": [ { "name": "site_id", "type": "string", "description": "The ID of the site that contains the snippet.", "readOnly": false, "required": true } ] } ], "UpsertSnippetRequest": [ { "name": "UpsertSnippetRequest", "properties": [ { "name": "snippet", "type": "#/components/schemas/Snippet", "description": "The snippet for the site.", "readOnly": false, "required": true }, { "name": "site_id", "type": "string", "description": "The ID of the site where you want to add or update the snippet.", "readOnly": false, "required": true } ] }, { "name": "Snippet", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID for the snippet.", "readOnly": true, "required": false }, { "name": "site_id", "type": "string", "description": "The ID of the site that contains the snippet.", "readOnly": true, "required": false }, { "name": "content", "type": "string", "description": "The snippet code, which can contain valid HTML, JavaScript, or both.", "readOnly": false, "required": true }, { "name": "created_at", "type": "string", "description": "The timestamp of when the snippet was initially added to the site, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp of when the snippet was last updated on the site, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "CreateSubscriptionRequest": [ { "name": "CreateSubscriptionRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `CreateSubscription` request.\nIf you do not provide a unique string (or provide an empty string as the value),\nthe endpoint treats each request as independent.\n\nFor more information, see [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the location the subscription is associated with.", "readOnly": false, "required": true }, { "name": "plan_variation_id", "type": "string", "description": "The ID of the [subscription plan variation](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations#plan-variations) created using the Catalog API.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the [customer](entity:Customer) subscribing to the subscription plan variation.", "readOnly": false, "required": true }, { "name": "start_date", "type": "string", "description": "The `YYYY-MM-DD`-formatted date to start the subscription. \nIf it is unspecified, the subscription starts immediately.", "readOnly": false, "required": false }, { "name": "canceled_date", "type": "string", "description": "The `YYYY-MM-DD`-formatted date when the newly created subscription is scheduled for cancellation. \n\nThis date overrides the cancellation date set in the plan variation configuration.\nIf the cancellation date is earlier than the end date of a subscription cycle, the subscription stops\nat the canceled date and the subscriber is sent a prorated invoice at the beginning of the canceled cycle. \n\nWhen the subscription plan of the newly created subscription has a fixed number of cycles and the `canceled_date`\noccurs before the subscription plan expires, the specified `canceled_date` sets the date when the subscription \nstops through the end of the last cycle.", "readOnly": false, "required": false }, { "name": "tax_percentage", "type": "string", "description": "The tax to add when billing the subscription.\nThe percentage is expressed in decimal form, using a `'.'` as the decimal\nseparator and without a `'%'` sign. For example, a value of 7.5\ncorresponds to 7.5%.", "readOnly": false, "required": false }, { "name": "price_override_money", "type": "#/components/schemas/Money", "description": "A custom price which overrides the cost of a subscription plan variation with `STATIC` pricing.\nThis field does not affect itemized subscriptions with `RELATIVE` pricing. Instead, \nyou should edit the Subscription's [order template](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions#phases-and-order-templates).", "readOnly": false, "required": false }, { "name": "card_id", "type": "string", "description": "The ID of the [subscriber's](entity:Customer) [card](entity:Card) to charge.\nIf it is not specified, the subscriber receives an invoice via email with a link to pay for their subscription.", "readOnly": false, "required": false }, { "name": "timezone", "type": "string", "description": "The timezone that is used in date calculations for the subscription. If unset, defaults to\nthe location timezone. If a timezone is not configured for the location, defaults to \"America/New_York\".\nFormat: the IANA Timezone Database identifier for the location timezone. For\na list of time zones, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "readOnly": false, "required": false }, { "name": "source", "type": "#/components/schemas/SubscriptionSource", "description": "The origination details of the subscription.", "readOnly": false, "required": false }, { "name": "monthly_billing_anchor_date", "type": "integer", "description": "The day-of-the-month to change the billing date to.", "readOnly": false, "required": false }, { "name": "phases", "type": "array", "description": "array of phases for this subscription", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Phase" } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "SubscriptionSource", "properties": [ { "name": "name", "type": "string", "description": "The name used to identify the place (physical or digital) that\na subscription originates. If unset, the name defaults to the name\nof the application that created the subscription.", "readOnly": false, "required": false } ] }, { "name": "Phase", "properties": [ { "name": "uid", "type": "string", "description": "id of subscription phase", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "index of phase in total subscription plan", "readOnly": false, "required": false }, { "name": "order_template_id", "type": "string", "description": "id of order to be used in billing", "readOnly": false, "required": false }, { "name": "plan_phase_uid", "type": "string", "description": "the uid from the plan's phase in catalog", "readOnly": false, "required": false } ] } ], "BulkSwapPlanRequest": [ { "name": "BulkSwapPlanRequest", "properties": [ { "name": "new_plan_variation_id", "type": "string", "description": "The ID of the new subscription plan variation.\n\nThis field is required.", "readOnly": false, "required": true }, { "name": "old_plan_variation_id", "type": "string", "description": "The ID of the plan variation whose subscriptions should be swapped. Active subscriptions\nusing this plan variation will be subscribed to the new plan variation on their next billing\nday.", "readOnly": false, "required": true }, { "name": "location_id", "type": "string", "description": "The ID of the location to associate with the swapped subscriptions.", "readOnly": false, "required": true } ] } ], "SearchSubscriptionsRequest": [ { "name": "SearchSubscriptionsRequest", "properties": [ { "name": "cursor", "type": "string", "description": "When the total number of resulting subscriptions exceeds the limit of a paged response, \nspecify the cursor returned from a preceding response here to fetch the next set of results.\nIf the cursor is unset, the response contains the last page of the results.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The upper limit on the number of subscriptions to return\nin a paged response.", "readOnly": false, "required": false }, { "name": "query", "type": "#/components/schemas/SearchSubscriptionsQuery", "description": "A subscription query consisting of specified filtering conditions.\n\nIf this `query` field is unspecified, the `SearchSubscriptions` call will return all subscriptions.", "readOnly": false, "required": false }, { "name": "include", "type": "array", "description": "An option to include related information in the response. \n\nThe supported values are: \n\n- `actions`: to include scheduled actions on the targeted subscriptions.", "readOnly": false, "required": false } ] }, { "name": "SearchSubscriptionsQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/SearchSubscriptionsFilter", "description": "A list of query expressions.", "readOnly": false, "required": false } ] }, { "name": "SearchSubscriptionsFilter", "properties": [ { "name": "customer_ids", "type": "array", "description": "A filter to select subscriptions based on the subscribing customer IDs.", "readOnly": false, "required": false }, { "name": "location_ids", "type": "array", "description": "A filter to select subscriptions based on the location.", "readOnly": false, "required": false }, { "name": "source_names", "type": "array", "description": "A filter to select subscriptions based on the source application.", "readOnly": false, "required": false } ] } ], "RetrieveSubscriptionRequest": [ { "name": "RetrieveSubscriptionRequest", "properties": [ { "name": "include", "type": "string", "description": "A query parameter to specify related information to be included in the response. \n\nThe supported query parameter values are: \n\n- `actions`: to include scheduled actions on the targeted subscription.", "readOnly": false, "required": false }, { "name": "subscription_id", "type": "string", "description": "The ID of the subscription to retrieve.", "readOnly": false, "required": true } ] } ], "UpdateSubscriptionRequest": [ { "name": "UpdateSubscriptionRequest", "properties": [ { "name": "subscription", "type": "#/components/schemas/Subscription", "description": "The subscription object containing the current version, and fields to update.\nUnset fields will be left at their current server values, and JSON `null` values will\nbe treated as a request to clear the relevant data.", "readOnly": false, "required": false }, { "name": "subscription_id", "type": "string", "description": "The ID of the subscription to update.", "readOnly": false, "required": true } ] }, { "name": "Subscription", "properties": [ { "name": "id", "type": "string", "description": "The Square-assigned ID of the subscription.", "readOnly": true, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the location associated with the subscription.", "readOnly": true, "required": false }, { "name": "plan_variation_id", "type": "string", "description": "The ID of the subscribed-to [subscription plan variation](entity:CatalogSubscriptionPlanVariation).", "readOnly": true, "required": false }, { "name": "customer_id", "type": "string", "description": "The ID of the subscribing [customer](entity:Customer) profile.", "readOnly": true, "required": false }, { "name": "start_date", "type": "string", "description": "The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) to start the subscription.", "readOnly": true, "required": false }, { "name": "canceled_date", "type": "string", "description": "The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) to cancel the subscription, \nwhen the subscription status changes to `CANCELED` and the subscription billing stops.\n\nIf this field is not set, the subscription ends according its subscription plan.\n\nThis field cannot be updated, other than being cleared.", "readOnly": false, "required": false }, { "name": "charged_through_date", "type": "string", "description": "The `YYYY-MM-DD`-formatted date up to when the subscriber is invoiced for the\nsubscription.\n\nAfter the invoice is sent for a given billing period,\nthis date will be the last day of the billing period.\nFor example,\nsuppose for the month of May a subscriber gets an invoice\n(or charged the card) on May 1. For the monthly billing scenario,\nthis date is then set to May 31.", "readOnly": true, "required": false }, { "name": "status", "type": "#/components/schemas/SubscriptionStatus", "description": "The current status of the subscription.\n", "readOnly": true, "required": false }, { "name": "tax_percentage", "type": "string", "description": "The tax amount applied when billing the subscription. The\npercentage is expressed in decimal form, using a `'.'` as the decimal\nseparator and without a `'%'` sign. For example, a value of `7.5`\ncorresponds to 7.5%.", "readOnly": false, "required": false }, { "name": "invoice_ids", "type": "array", "description": "The IDs of the [invoices](entity:Invoice) created for the\nsubscription, listed in order when the invoices were created\n(newest invoices appear first).", "readOnly": true, "required": false }, { "name": "price_override_money", "type": "#/components/schemas/Money", "description": "A custom price which overrides the cost of a subscription plan variation with `STATIC` pricing.\nThis field does not affect itemized subscriptions with `RELATIVE` pricing. Instead, \nyou should edit the Subscription's [order template](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions#phases-and-order-templates).", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The version of the object. When updating an object, the version\nsupplied must match the version in the database, otherwise the write will\nbe rejected as conflicting.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the subscription was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "card_id", "type": "string", "description": "The ID of the [subscriber's](entity:Customer) [card](entity:Card)\nused to charge for the subscription.", "readOnly": false, "required": false }, { "name": "timezone", "type": "string", "description": "Timezone that will be used in date calculations for the subscription.\nDefaults to the timezone of the location based on `location_id`.\nFormat: the IANA Timezone Database identifier for the location timezone (for example, `America/Los_Angeles`).", "readOnly": true, "required": false }, { "name": "source", "type": "#/components/schemas/SubscriptionSource", "description": "The origination details of the subscription.", "readOnly": false, "required": false }, { "name": "actions", "type": "array", "description": "The list of scheduled actions on this subscription. It is set only in the response from \n[RetrieveSubscription](api-endpoint:Subscriptions-RetrieveSubscription) with the query parameter\nof `include=actions` or from \n[SearchSubscriptions](api-endpoint:Subscriptions-SearchSubscriptions) with the input parameter \nof `include:[\"actions\"]`.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/SubscriptionAction" }, { "name": "monthly_billing_anchor_date", "type": "integer", "description": "The day of the month on which the subscription will issue invoices and publish orders.", "readOnly": true, "required": false }, { "name": "phases", "type": "array", "description": "array of phases for this subscription", "readOnly": true, "required": false, "arrayType": "#/components/schemas/Phase" } ] }, { "name": "SubscriptionStatus", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "SubscriptionSource", "properties": [ { "name": "name", "type": "string", "description": "The name used to identify the place (physical or digital) that\na subscription originates. If unset, the name defaults to the name\nof the application that created the subscription.", "readOnly": false, "required": false } ] }, { "name": "SubscriptionAction", "properties": [ { "name": "id", "type": "string", "description": "The ID of an action scoped to a subscription.", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/SubscriptionActionType", "description": "The type of the action.\n", "readOnly": false, "required": false }, { "name": "effective_date", "type": "string", "description": "The `YYYY-MM-DD`-formatted date when the action occurs on the subscription.", "readOnly": false, "required": false }, { "name": "monthly_billing_anchor_date", "type": "integer", "description": "The new billing anchor day value, for a `CHANGE_BILLING_ANCHOR_DATE` action.", "readOnly": false, "required": false }, { "name": "phases", "type": "array", "description": "A list of Phases, to pass phase-specific information used in the swap.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/Phase" }, { "name": "new_plan_variation_id", "type": "string", "description": "The target subscription plan variation that a subscription switches to, for a `SWAP_PLAN` action.", "readOnly": false, "required": false } ] }, { "name": "SubscriptionActionType", "properties": [] }, { "name": "Phase", "properties": [ { "name": "uid", "type": "string", "description": "id of subscription phase", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "index of phase in total subscription plan", "readOnly": false, "required": false }, { "name": "order_template_id", "type": "string", "description": "id of order to be used in billing", "readOnly": false, "required": false }, { "name": "plan_phase_uid", "type": "string", "description": "the uid from the plan's phase in catalog", "readOnly": false, "required": false } ] } ], "DeleteSubscriptionActionRequest": [ { "name": "DeleteSubscriptionActionRequest", "properties": [ { "name": "subscription_id", "type": "string", "description": "The ID of the subscription the targeted action is to act upon.", "readOnly": false, "required": true }, { "name": "action_id", "type": "string", "description": "The ID of the targeted action to be deleted.", "readOnly": false, "required": true } ] } ], "ChangeBillingAnchorDateRequest": [ { "name": "ChangeBillingAnchorDateRequest", "properties": [ { "name": "monthly_billing_anchor_date", "type": "integer", "description": "The anchor day for the billing cycle.", "readOnly": false, "required": false }, { "name": "effective_date", "type": "string", "description": "The `YYYY-MM-DD`-formatted date when the scheduled `BILLING_ANCHOR_CHANGE` action takes\nplace on the subscription.\n\nWhen this date is unspecified or falls within the current billing cycle, the billing anchor date\nis changed immediately.", "readOnly": false, "required": false }, { "name": "subscription_id", "type": "string", "description": "The ID of the subscription to update the billing anchor date.", "readOnly": false, "required": true } ] } ], "CancelSubscriptionRequest": [ { "name": "CancelSubscriptionRequest", "properties": [ { "name": "subscription_id", "type": "string", "description": "The ID of the subscription to cancel.", "readOnly": false, "required": true } ] } ], "ListSubscriptionEventsRequest": [ { "name": "ListSubscriptionEventsRequest", "properties": [ { "name": "cursor", "type": "string", "description": "When the total number of resulting subscription events exceeds the limit of a paged response, \nspecify the cursor returned from a preceding response here to fetch the next set of results.\nIf the cursor is unset, the response contains the last page of the results.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The upper limit on the number of subscription events to return\nin a paged response.", "readOnly": false, "required": false }, { "name": "subscription_id", "type": "string", "description": "The ID of the subscription to retrieve the events for.", "readOnly": false, "required": true } ] } ], "PauseSubscriptionRequest": [ { "name": "PauseSubscriptionRequest", "properties": [ { "name": "pause_effective_date", "type": "string", "description": "The `YYYY-MM-DD`-formatted date when the scheduled `PAUSE` action takes place on the subscription.\n\nWhen this date is unspecified or falls within the current billing cycle, the subscription is paused\non the starting date of the next billing cycle.", "readOnly": false, "required": false }, { "name": "pause_cycle_duration", "type": "integer", "description": "The number of billing cycles the subscription will be paused before it is reactivated. \n\nWhen this is set, a `RESUME` action is also scheduled to take place on the subscription at \nthe end of the specified pause cycle duration. In this case, neither `resume_effective_date` \nnor `resume_change_timing` may be specified.", "readOnly": false, "required": false }, { "name": "resume_effective_date", "type": "string", "description": "The date when the subscription is reactivated by a scheduled `RESUME` action. \nThis date must be at least one billing cycle ahead of `pause_effective_date`.", "readOnly": false, "required": false }, { "name": "resume_change_timing", "type": "#/components/schemas/ChangeTiming", "description": "The timing whether the subscription is reactivated immediately or at the end of the billing cycle, relative to \n`resume_effective_date`.\n", "readOnly": false, "required": false }, { "name": "pause_reason", "type": "string", "description": "The user-provided reason to pause the subscription.", "readOnly": false, "required": false }, { "name": "subscription_id", "type": "string", "description": "The ID of the subscription to pause.", "readOnly": false, "required": true } ] }, { "name": "ChangeTiming", "properties": [] } ], "ResumeSubscriptionRequest": [ { "name": "ResumeSubscriptionRequest", "properties": [ { "name": "resume_effective_date", "type": "string", "description": "The `YYYY-MM-DD`-formatted date when the subscription reactivated.", "readOnly": false, "required": false }, { "name": "resume_change_timing", "type": "#/components/schemas/ChangeTiming", "description": "The timing to resume a subscription, relative to the specified\n`resume_effective_date` attribute value.\n", "readOnly": false, "required": false }, { "name": "subscription_id", "type": "string", "description": "The ID of the subscription to resume.", "readOnly": false, "required": true } ] }, { "name": "ChangeTiming", "properties": [] } ], "SwapPlanRequest": [ { "name": "SwapPlanRequest", "properties": [ { "name": "new_plan_variation_id", "type": "string", "description": "The ID of the new subscription plan variation.\n\nThis field is required.", "readOnly": false, "required": false }, { "name": "phases", "type": "array", "description": "A list of PhaseInputs, to pass phase-specific information used in the swap.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/PhaseInput" }, { "name": "subscription_id", "type": "string", "description": "The ID of the subscription to swap the subscription plan for.", "readOnly": false, "required": true } ] }, { "name": "PhaseInput", "properties": [ { "name": "ordinal", "type": "integer", "description": "index of phase in total subscription plan", "readOnly": false, "required": true }, { "name": "order_template_id", "type": "string", "description": "id of order to be used in billing", "readOnly": false, "required": false } ] } ], "CreateTeamMemberRequest": [ { "name": "CreateTeamMemberRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `CreateTeamMember` request.\nKeys can be any valid string, but must be unique for every request.\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).\n\nThe minimum length is 1 and the maximum length is 45.", "readOnly": false, "required": false }, { "name": "team_member", "type": "#/components/schemas/TeamMember", "description": "**Required** The data used to create the `TeamMember` object. If you include `wage_setting`, you must provide\n`job_id` for each job assignment. To get job IDs, call [ListJobs](api-endpoint:Team-ListJobs).", "readOnly": false, "required": false } ] }, { "name": "TeamMember", "properties": [ { "name": "id", "type": "string", "description": "The unique ID for the team member.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "A second ID used to associate the team member with an entity in another system.", "readOnly": false, "required": false }, { "name": "is_owner", "type": "boolean", "description": "Whether the team member is the owner of the Square account.", "readOnly": true, "required": false }, { "name": "status", "type": "#/components/schemas/TeamMemberStatus", "description": "Describes the status of the team member.\n", "readOnly": false, "required": false }, { "name": "given_name", "type": "string", "description": "The given name (that is, the first name) associated with the team member.", "readOnly": false, "required": false }, { "name": "family_name", "type": "string", "description": "The family name (that is, the last name) associated with the team member.", "readOnly": false, "required": false }, { "name": "email_address", "type": "string", "description": "The email address associated with the team member. After accepting the invitation\nfrom Square, only the team member can change this value.", "readOnly": false, "required": false }, { "name": "phone_number", "type": "string", "description": "The team member's phone number, in E.164 format. For example:\n+14155552671 - the country code is 1 for US\n+551155256325 - the country code is 55 for BR", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the team member was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the team member was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "assigned_locations", "type": "#/components/schemas/TeamMemberAssignedLocations", "description": "Describes the team member's assigned locations.", "readOnly": false, "required": false }, { "name": "wage_setting", "type": "#/components/schemas/WageSetting", "description": "Information about the team member's overtime exemption status, job assignments, and compensation.", "readOnly": false, "required": false } ] }, { "name": "TeamMemberStatus", "properties": [] }, { "name": "TeamMemberAssignedLocations", "properties": [ { "name": "assignment_type", "type": "#/components/schemas/TeamMemberAssignedLocationsAssignmentType", "description": "The current assignment type of the team member.\n", "readOnly": false, "required": false }, { "name": "location_ids", "type": "array", "description": "The explicit locations that the team member is assigned to.", "readOnly": false, "required": false } ] }, { "name": "TeamMemberAssignedLocationsAssignmentType", "properties": [] }, { "name": "WageSetting", "properties": [ { "name": "team_member_id", "type": "string", "description": "The ID of the team member associated with the wage setting.", "readOnly": false, "required": false }, { "name": "job_assignments", "type": "array", "description": "**Required** The ordered list of jobs that the team member is assigned to.\nThe first job assignment is considered the team member's primary job.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/JobAssignment" }, { "name": "is_overtime_exempt", "type": "boolean", "description": "Whether the team member is exempt from the overtime rules of the seller's country.", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "**Read only** Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If not provided,\nSquare executes a blind write, potentially overwriting data from another write. For more information,\nsee [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency).", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the wage setting was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the wage setting was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "JobAssignment", "properties": [ { "name": "job_title", "type": "string", "description": "The title of the job.", "readOnly": false, "required": false }, { "name": "pay_type", "type": "#/components/schemas/JobAssignmentPayType", "description": "The current pay type for the job assignment used to\ncalculate the pay amount in a pay period.\n", "readOnly": false, "required": true }, { "name": "hourly_rate", "type": "#/components/schemas/Money", "description": "The hourly pay rate of the job. For `SALARY` pay types, Square calculates the hourly rate based on\n`annual_rate` and `weekly_hours`.", "readOnly": false, "required": false }, { "name": "annual_rate", "type": "#/components/schemas/Money", "description": "The total pay amount for a 12-month period on the job. Set if the job `PayType` is `SALARY`.", "readOnly": false, "required": false }, { "name": "weekly_hours", "type": "integer", "description": "The planned hours per week for the job. Set if the job `PayType` is `SALARY`.", "readOnly": false, "required": false }, { "name": "job_id", "type": "string", "description": "The ID of the [job](entity:Job).", "readOnly": false, "required": false } ] }, { "name": "JobAssignmentPayType", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] } ], "BulkCreateTeamMembersRequest": [ { "name": "BulkCreateTeamMembersRequest", "properties": [ { "name": "team_members", "type": "map", "description": "The data used to create the `TeamMember` objects. Each key is the `idempotency_key` that maps to the `CreateTeamMemberRequest`.\nThe maximum number of create objects is 25.\n\nIf you include a team member's `wage_setting`, you must provide `job_id` for each job assignment. To get job IDs,\ncall [ListJobs](api-endpoint:Team-ListJobs).", "readOnly": false, "required": true } ] } ], "BulkUpdateTeamMembersRequest": [ { "name": "BulkUpdateTeamMembersRequest", "properties": [ { "name": "team_members", "type": "map", "description": "The data used to update the `TeamMember` objects. Each key is the `team_member_id` that maps to the `UpdateTeamMemberRequest`.\nThe maximum number of update objects is 25.\n\nFor each team member, include the fields to add, change, or clear. Fields can be cleared using a null value.\nTo update `wage_setting.job_assignments`, you must provide the complete list of job assignments. If needed,\ncall [ListJobs](api-endpoint:Team-ListJobs) to get the required `job_id` values.", "readOnly": false, "required": true } ] } ], "ListJobsRequest": [ { "name": "ListJobsRequest", "properties": [ { "name": "cursor", "type": "string", "description": "The pagination cursor returned by the previous call to this endpoint. Provide this\ncursor to retrieve the next page of results for your original request. For more information,\nsee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false } ] } ], "CreateJobRequest": [ { "name": "CreateJobRequest", "properties": [ { "name": "job", "type": "#/components/schemas/Job", "description": "The job to create. The `title` field is required and `is_tip_eligible` defaults to true.", "readOnly": false, "required": true }, { "name": "idempotency_key", "type": "string", "description": "A unique identifier for the `CreateJob` request. Keys can be any valid string,\nbut must be unique for each request. For more information, see\n[Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).", "readOnly": false, "required": true } ] }, { "name": "Job", "properties": [ { "name": "id", "type": "string", "description": "**Read only** The unique Square-assigned ID of the job. If you need a job ID for an API request,\ncall [ListJobs](api-endpoint:Team-ListJobs) or use the ID returned when you created the job.\nYou can also get job IDs from a team member's wage setting.", "readOnly": false, "required": false }, { "name": "title", "type": "string", "description": "The title of the job.", "readOnly": false, "required": false }, { "name": "is_tip_eligible", "type": "boolean", "description": "Indicates whether team members can earn tips for the job.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the job was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the job was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "**Read only** The current version of the job. Include this field in `UpdateJob` requests to enable\n[optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency)\ncontrol and avoid overwrites from concurrent requests. Requests fail if the provided version doesn't\nmatch the server version at the time of the request.", "readOnly": false, "required": false } ] } ], "RetrieveJobRequest": [ { "name": "RetrieveJobRequest", "properties": [ { "name": "job_id", "type": "string", "description": "The ID of the job to retrieve.", "readOnly": false, "required": true } ] } ], "UpdateJobRequest": [ { "name": "UpdateJobRequest", "properties": [ { "name": "job", "type": "#/components/schemas/Job", "description": "The job with the updated fields, either `title`, `is_tip_eligible`, or both. Only changed fields need\nto be included in the request. Optionally include `version` to enable optimistic concurrency control.", "readOnly": false, "required": true }, { "name": "job_id", "type": "string", "description": "The ID of the job to update.", "readOnly": false, "required": true } ] }, { "name": "Job", "properties": [ { "name": "id", "type": "string", "description": "**Read only** The unique Square-assigned ID of the job. If you need a job ID for an API request,\ncall [ListJobs](api-endpoint:Team-ListJobs) or use the ID returned when you created the job.\nYou can also get job IDs from a team member's wage setting.", "readOnly": false, "required": false }, { "name": "title", "type": "string", "description": "The title of the job.", "readOnly": false, "required": false }, { "name": "is_tip_eligible", "type": "boolean", "description": "Indicates whether team members can earn tips for the job.", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the job was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the job was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "version", "type": "integer", "description": "**Read only** The current version of the job. Include this field in `UpdateJob` requests to enable\n[optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency)\ncontrol and avoid overwrites from concurrent requests. Requests fail if the provided version doesn't\nmatch the server version at the time of the request.", "readOnly": false, "required": false } ] } ], "SearchTeamMembersRequest": [ { "name": "SearchTeamMembersRequest", "properties": [ { "name": "query", "type": "#/components/schemas/SearchTeamMembersQuery", "description": "The query parameters.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of `TeamMember` objects in a page (100 by default).", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "The opaque cursor for fetching the next page. For more information, see\n[pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "readOnly": false, "required": false } ] }, { "name": "SearchTeamMembersQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/SearchTeamMembersFilter", "description": "The options to filter by.", "readOnly": false, "required": false } ] }, { "name": "SearchTeamMembersFilter", "properties": [ { "name": "location_ids", "type": "array", "description": "When present, filters by team members assigned to the specified locations.\nWhen empty, includes team members assigned to any location.", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/TeamMemberStatus", "description": "When present, filters by team members who match the given status.\nWhen empty, includes team members of all statuses.\n", "readOnly": false, "required": false }, { "name": "is_owner", "type": "boolean", "description": "When present and set to true, returns the team member who is the owner of the Square account.", "readOnly": false, "required": false } ] }, { "name": "TeamMemberStatus", "properties": [] } ], "RetrieveTeamMemberRequest": [ { "name": "RetrieveTeamMemberRequest", "properties": [ { "name": "team_member_id", "type": "string", "description": "The ID of the team member to retrieve.", "readOnly": false, "required": true } ] } ], "UpdateTeamMemberRequest": [ { "name": "UpdateTeamMemberRequest", "properties": [ { "name": "team_member", "type": "#/components/schemas/TeamMember", "description": "The team member fields to add, change, or clear. Fields can be cleared using a null value. To update\n`wage_setting.job_assignments`, you must provide the complete list of job assignments. If needed, call\n[ListJobs](api-endpoint:Team-ListJobs) to get the required `job_id` values.", "readOnly": false, "required": false }, { "name": "team_member_id", "type": "string", "description": "The ID of the team member to update.", "readOnly": false, "required": true } ] }, { "name": "TeamMember", "properties": [ { "name": "id", "type": "string", "description": "The unique ID for the team member.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "A second ID used to associate the team member with an entity in another system.", "readOnly": false, "required": false }, { "name": "is_owner", "type": "boolean", "description": "Whether the team member is the owner of the Square account.", "readOnly": true, "required": false }, { "name": "status", "type": "#/components/schemas/TeamMemberStatus", "description": "Describes the status of the team member.\n", "readOnly": false, "required": false }, { "name": "given_name", "type": "string", "description": "The given name (that is, the first name) associated with the team member.", "readOnly": false, "required": false }, { "name": "family_name", "type": "string", "description": "The family name (that is, the last name) associated with the team member.", "readOnly": false, "required": false }, { "name": "email_address", "type": "string", "description": "The email address associated with the team member. After accepting the invitation\nfrom Square, only the team member can change this value.", "readOnly": false, "required": false }, { "name": "phone_number", "type": "string", "description": "The team member's phone number, in E.164 format. For example:\n+14155552671 - the country code is 1 for US\n+551155256325 - the country code is 55 for BR", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the team member was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the team member was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "assigned_locations", "type": "#/components/schemas/TeamMemberAssignedLocations", "description": "Describes the team member's assigned locations.", "readOnly": false, "required": false }, { "name": "wage_setting", "type": "#/components/schemas/WageSetting", "description": "Information about the team member's overtime exemption status, job assignments, and compensation.", "readOnly": false, "required": false } ] }, { "name": "TeamMemberStatus", "properties": [] }, { "name": "TeamMemberAssignedLocations", "properties": [ { "name": "assignment_type", "type": "#/components/schemas/TeamMemberAssignedLocationsAssignmentType", "description": "The current assignment type of the team member.\n", "readOnly": false, "required": false }, { "name": "location_ids", "type": "array", "description": "The explicit locations that the team member is assigned to.", "readOnly": false, "required": false } ] }, { "name": "TeamMemberAssignedLocationsAssignmentType", "properties": [] }, { "name": "WageSetting", "properties": [ { "name": "team_member_id", "type": "string", "description": "The ID of the team member associated with the wage setting.", "readOnly": false, "required": false }, { "name": "job_assignments", "type": "array", "description": "**Required** The ordered list of jobs that the team member is assigned to.\nThe first job assignment is considered the team member's primary job.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/JobAssignment" }, { "name": "is_overtime_exempt", "type": "boolean", "description": "Whether the team member is exempt from the overtime rules of the seller's country.", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "**Read only** Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If not provided,\nSquare executes a blind write, potentially overwriting data from another write. For more information,\nsee [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency).", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the wage setting was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the wage setting was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "JobAssignment", "properties": [ { "name": "job_title", "type": "string", "description": "The title of the job.", "readOnly": false, "required": false }, { "name": "pay_type", "type": "#/components/schemas/JobAssignmentPayType", "description": "The current pay type for the job assignment used to\ncalculate the pay amount in a pay period.\n", "readOnly": false, "required": true }, { "name": "hourly_rate", "type": "#/components/schemas/Money", "description": "The hourly pay rate of the job. For `SALARY` pay types, Square calculates the hourly rate based on\n`annual_rate` and `weekly_hours`.", "readOnly": false, "required": false }, { "name": "annual_rate", "type": "#/components/schemas/Money", "description": "The total pay amount for a 12-month period on the job. Set if the job `PayType` is `SALARY`.", "readOnly": false, "required": false }, { "name": "weekly_hours", "type": "integer", "description": "The planned hours per week for the job. Set if the job `PayType` is `SALARY`.", "readOnly": false, "required": false }, { "name": "job_id", "type": "string", "description": "The ID of the [job](entity:Job).", "readOnly": false, "required": false } ] }, { "name": "JobAssignmentPayType", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] } ], "RetrieveWageSettingRequest": [ { "name": "RetrieveWageSettingRequest", "properties": [ { "name": "team_member_id", "type": "string", "description": "The ID of the team member for which to retrieve the wage setting.", "readOnly": false, "required": true } ] } ], "UpdateWageSettingRequest": [ { "name": "UpdateWageSettingRequest", "properties": [ { "name": "wage_setting", "type": "#/components/schemas/WageSetting", "description": "The complete `WageSetting` object. For all job assignments, specify one of the following:\n- `job_id` (recommended) - If needed, call [ListJobs](api-endpoint:Team-ListJobs) to get a list of all jobs.\nRequires Square API version 2024-12-18 or later.\n- `job_title` - Use the exact, case-sensitive spelling of an existing title unless you want to create a new job.\nThis value is ignored if `job_id` is also provided.", "readOnly": false, "required": true }, { "name": "team_member_id", "type": "string", "description": "The ID of the team member for which to update the `WageSetting` object.", "readOnly": false, "required": true } ] }, { "name": "WageSetting", "properties": [ { "name": "team_member_id", "type": "string", "description": "The ID of the team member associated with the wage setting.", "readOnly": false, "required": false }, { "name": "job_assignments", "type": "array", "description": "**Required** The ordered list of jobs that the team member is assigned to.\nThe first job assignment is considered the team member's primary job.", "readOnly": false, "required": false, "arrayType": "#/components/schemas/JobAssignment" }, { "name": "is_overtime_exempt", "type": "boolean", "description": "Whether the team member is exempt from the overtime rules of the seller's country.", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "**Read only** Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If not provided,\nSquare executes a blind write, potentially overwriting data from another write. For more information,\nsee [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency).", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp when the wage setting was created, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp when the wage setting was last updated, in RFC 3339 format.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] }, { "name": "JobAssignment", "properties": [ { "name": "job_title", "type": "string", "description": "The title of the job.", "readOnly": false, "required": false }, { "name": "pay_type", "type": "#/components/schemas/JobAssignmentPayType", "description": "The current pay type for the job assignment used to\ncalculate the pay amount in a pay period.\n", "readOnly": false, "required": true }, { "name": "hourly_rate", "type": "#/components/schemas/Money", "description": "The hourly pay rate of the job. For `SALARY` pay types, Square calculates the hourly rate based on\n`annual_rate` and `weekly_hours`.", "readOnly": false, "required": false }, { "name": "annual_rate", "type": "#/components/schemas/Money", "description": "The total pay amount for a 12-month period on the job. Set if the job `PayType` is `SALARY`.", "readOnly": false, "required": false }, { "name": "weekly_hours", "type": "integer", "description": "The planned hours per week for the job. Set if the job `PayType` is `SALARY`.", "readOnly": false, "required": false }, { "name": "job_id", "type": "string", "description": "The ID of the [job](entity:Job).", "readOnly": false, "required": false } ] }, { "name": "JobAssignmentPayType", "properties": [] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] } ], "CreateTerminalActionRequest": [ { "name": "CreateTerminalActionRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `CreateAction` request. Keys can be any valid string\nbut must be unique for every `CreateAction` request.\n\nSee [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more\ninformation.", "readOnly": false, "required": true }, { "name": "action", "type": "#/components/schemas/TerminalAction", "description": "The Action to create.", "readOnly": false, "required": true } ] }, { "name": "TerminalAction", "properties": [ { "name": "id", "type": "string", "description": "A unique ID for this `TerminalAction`.", "readOnly": true, "required": false }, { "name": "device_id", "type": "string", "description": "The unique Id of the device intended for this `TerminalAction`.\nThe Id can be retrieved from /v2/devices api.", "readOnly": false, "required": false }, { "name": "deadline_duration", "type": "string", "description": "The duration as an RFC 3339 duration, after which the action will be automatically canceled.\nTerminalActions that are `PENDING` will be automatically `CANCELED` and have a cancellation reason\nof `TIMED_OUT`\n\nDefault: 5 minutes from creation\n\nMaximum: 5 minutes\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "status", "type": "string", "description": "The status of the `TerminalAction`.\nOptions: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, `COMPLETED`", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "#/components/schemas/ActionCancelReason", "description": "The reason why `TerminalAction` is canceled. Present if the status is `CANCELED`.\n", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The time when the `TerminalAction` was created as an RFC 3339 timestamp.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The time when the `TerminalAction` was last updated as an RFC 3339 timestamp.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "app_id", "type": "string", "description": "The ID of the application that created the action.", "readOnly": true, "required": false }, { "name": "location_id", "type": "string", "description": "The location id the action is attached to, if a link can be made.", "readOnly": true, "required": false }, { "name": "type", "type": "#/components/schemas/TerminalActionActionType", "description": "Represents the type of the action.\n", "readOnly": false, "required": false }, { "name": "qr_code_options", "type": "#/components/schemas/QrCodeOptions", "description": "Describes configuration for the QR code action. Requires `QR_CODE` type.", "readOnly": false, "required": false }, { "name": "save_card_options", "type": "#/components/schemas/SaveCardOptions", "description": "Describes configuration for the save-card action. Requires `SAVE_CARD` type.", "readOnly": false, "required": false }, { "name": "signature_options", "type": "#/components/schemas/SignatureOptions", "description": "Describes configuration for the signature capture action. Requires `SIGNATURE` type.", "readOnly": false, "required": false }, { "name": "confirmation_options", "type": "#/components/schemas/ConfirmationOptions", "description": "Describes configuration for the confirmation action. Requires `CONFIRMATION` type.", "readOnly": false, "required": false }, { "name": "receipt_options", "type": "#/components/schemas/ReceiptOptions", "description": "Describes configuration for the receipt action. Requires `RECEIPT` type.", "readOnly": false, "required": false }, { "name": "data_collection_options", "type": "#/components/schemas/DataCollectionOptions", "description": "Describes configuration for the data collection action. Requires `DATA_COLLECTION` type.", "readOnly": false, "required": false }, { "name": "select_options", "type": "#/components/schemas/SelectOptions", "description": "Describes configuration for the select action. Requires `SELECT` type.", "readOnly": false, "required": false }, { "name": "device_metadata", "type": "#/components/schemas/DeviceMetadata", "description": "Details about the Terminal that received the action request (such as battery level,\noperating system version, and network connection settings).\n\nOnly available for `PING` action type.", "readOnly": true, "required": false }, { "name": "await_next_action", "type": "boolean", "description": "Indicates the action will be linked to another action and requires a waiting dialog to be\ndisplayed instead of returning to the idle screen on completion of the action.\n\nOnly supported on SIGNATURE, CONFIRMATION, DATA_COLLECTION, and SELECT types.", "readOnly": false, "required": false }, { "name": "await_next_action_duration", "type": "string", "description": "The timeout duration of the waiting dialog as an RFC 3339 duration, after which the\nwaiting dialog will no longer be displayed and the Terminal will return to the idle screen.\n\nDefault: 5 minutes from when the waiting dialog is displayed\n\nMaximum: 5 minutes\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false } ] }, { "name": "ActionCancelReason", "properties": [] }, { "name": "TerminalActionActionType", "properties": [] }, { "name": "QrCodeOptions", "properties": [ { "name": "title", "type": "string", "description": "The title text to display in the QR code flow on the Terminal.", "readOnly": false, "required": true }, { "name": "body", "type": "string", "description": "The body text to display in the QR code flow on the Terminal.", "readOnly": false, "required": true }, { "name": "barcode_contents", "type": "string", "description": "The text representation of the data to show in the QR code\nas UTF8-encoded data.", "readOnly": false, "required": true } ] }, { "name": "SaveCardOptions", "properties": [ { "name": "customer_id", "type": "string", "description": "The square-assigned ID of the customer linked to the saved card.", "readOnly": false, "required": true }, { "name": "card_id", "type": "string", "description": "The id of the created card-on-file.", "readOnly": true, "required": false }, { "name": "reference_id", "type": "string", "description": "An optional user-defined reference ID that can be used to associate\nthis `Card` to another entity in an external system. For example, a customer\nID generated by a third-party system.", "readOnly": false, "required": false } ] }, { "name": "SignatureOptions", "properties": [ { "name": "title", "type": "string", "description": "The title text to display in the signature capture flow on the Terminal.", "readOnly": false, "required": true }, { "name": "body", "type": "string", "description": "The body text to display in the signature capture flow on the Terminal.", "readOnly": false, "required": true }, { "name": "signature", "type": "array", "description": "An image representation of the collected signature.", "readOnly": true, "required": false, "arrayType": "#/components/schemas/SignatureImage" } ] }, { "name": "SignatureImage", "properties": [ { "name": "image_type", "type": "string", "description": "The mime/type of the image data.\nUse `image/png;base64` for png.", "readOnly": true, "required": false }, { "name": "data", "type": "string", "description": "The base64 representation of the image.", "readOnly": true, "required": false } ] }, { "name": "ConfirmationOptions", "properties": [ { "name": "title", "type": "string", "description": "The title text to display in the confirmation screen flow on the Terminal.", "readOnly": false, "required": true }, { "name": "body", "type": "string", "description": "The agreement details to display in the confirmation flow on the Terminal.", "readOnly": false, "required": true }, { "name": "agree_button_text", "type": "string", "description": "The button text to display indicating the customer agrees to the displayed terms.", "readOnly": false, "required": true }, { "name": "disagree_button_text", "type": "string", "description": "The button text to display indicating the customer does not agree to the displayed terms.", "readOnly": false, "required": false }, { "name": "decision", "type": "#/components/schemas/ConfirmationDecision", "description": "The result of the buyer’s actions when presented with the confirmation screen.", "readOnly": true, "required": false } ] }, { "name": "ConfirmationDecision", "properties": [ { "name": "has_agreed", "type": "boolean", "description": "The buyer's decision to the displayed terms.", "readOnly": true, "required": false } ] }, { "name": "ReceiptOptions", "properties": [ { "name": "payment_id", "type": "string", "description": "The reference to the Square payment ID for the receipt.", "readOnly": false, "required": true }, { "name": "print_only", "type": "boolean", "description": "Instructs the device to print the receipt without displaying the receipt selection screen.\nRequires `printer_enabled` set to true.\nDefaults to false.", "readOnly": false, "required": false }, { "name": "is_duplicate", "type": "boolean", "description": "Identify the receipt as a reprint rather than an original receipt.\nDefaults to false.", "readOnly": false, "required": false } ] }, { "name": "DataCollectionOptions", "properties": [ { "name": "title", "type": "string", "description": "The title text to display in the data collection flow on the Terminal.", "readOnly": false, "required": true }, { "name": "body", "type": "string", "description": "The body text to display under the title in the data collection screen flow on the\nTerminal.", "readOnly": false, "required": true }, { "name": "input_type", "type": "#/components/schemas/DataCollectionOptionsInputType", "description": "Represents the type of the input text.\n", "readOnly": false, "required": true }, { "name": "collected_data", "type": "#/components/schemas/CollectedData", "description": "The buyer’s input text from the data collection screen.", "readOnly": true, "required": false } ] }, { "name": "DataCollectionOptionsInputType", "properties": [] }, { "name": "CollectedData", "properties": [ { "name": "input_text", "type": "string", "description": "The buyer's input text.", "readOnly": true, "required": false } ] }, { "name": "SelectOptions", "properties": [ { "name": "title", "type": "string", "description": "The title text to display in the select flow on the Terminal.", "readOnly": false, "required": true }, { "name": "body", "type": "string", "description": "The body text to display in the select flow on the Terminal.", "readOnly": false, "required": true }, { "name": "options", "type": "array", "description": "Represents the buttons/options that should be displayed in the select flow on the Terminal.", "readOnly": false, "required": true, "arrayType": "#/components/schemas/SelectOption" }, { "name": "selected_option", "type": "#/components/schemas/SelectOption", "description": "The buyer’s selected option.", "readOnly": true, "required": false } ] }, { "name": "SelectOption", "properties": [ { "name": "reference_id", "type": "string", "description": "The reference id for the option.", "readOnly": false, "required": true }, { "name": "title", "type": "string", "description": "The title text that displays in the select option button.", "readOnly": false, "required": true } ] }, { "name": "DeviceMetadata", "properties": [ { "name": "battery_percentage", "type": "string", "description": "The Terminal’s remaining battery percentage, between 1-100.", "readOnly": false, "required": false }, { "name": "charging_state", "type": "string", "description": "The current charging state of the Terminal.\nOptions: `CHARGING`, `NOT_CHARGING`", "readOnly": false, "required": false }, { "name": "location_id", "type": "string", "description": "The ID of the Square seller business location associated with the Terminal.", "readOnly": false, "required": false }, { "name": "merchant_id", "type": "string", "description": "The ID of the Square merchant account that is currently signed-in to the Terminal.", "readOnly": false, "required": false }, { "name": "network_connection_type", "type": "string", "description": "The Terminal’s current network connection type.\nOptions: `WIFI`, `ETHERNET`", "readOnly": false, "required": false }, { "name": "payment_region", "type": "string", "description": "The country in which the Terminal is authorized to take payments.", "readOnly": false, "required": false }, { "name": "serial_number", "type": "string", "description": "The unique identifier assigned to the Terminal, which can be found on the lower back\nof the device.", "readOnly": false, "required": false }, { "name": "os_version", "type": "string", "description": "The current version of the Terminal’s operating system.", "readOnly": false, "required": false }, { "name": "app_version", "type": "string", "description": "The current version of the application running on the Terminal.", "readOnly": false, "required": false }, { "name": "wifi_network_name", "type": "string", "description": "The name of the Wi-Fi network to which the Terminal is connected.", "readOnly": false, "required": false }, { "name": "wifi_network_strength", "type": "string", "description": "The signal strength of the Wi-FI network connection.\nOptions: `POOR`, `FAIR`, `GOOD`, `EXCELLENT`", "readOnly": false, "required": false }, { "name": "ip_address", "type": "string", "description": "The IP address of the Terminal.", "readOnly": false, "required": false } ] } ], "SearchTerminalActionsRequest": [ { "name": "SearchTerminalActionsRequest", "properties": [ { "name": "query", "type": "#/components/schemas/TerminalActionQuery", "description": "Queries terminal actions based on given conditions and sort order.\nLeaving this unset will return all actions with the default sort order.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for the original query.\nSee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more\ninformation.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "Limit the number of results returned for a single request.", "readOnly": false, "required": false } ] }, { "name": "TerminalActionQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/TerminalActionQueryFilter", "description": "Options for filtering returned `TerminalAction`s", "readOnly": false, "required": false }, { "name": "sort", "type": "#/components/schemas/TerminalActionQuerySort", "description": "Option for sorting returned `TerminalAction` objects.", "readOnly": false, "required": false } ] }, { "name": "TerminalActionQueryFilter", "properties": [ { "name": "device_id", "type": "string", "description": "`TerminalAction`s associated with a specific device. If no device is specified then all\n`TerminalAction`s for the merchant will be displayed.", "readOnly": false, "required": false }, { "name": "created_at", "type": "#/components/schemas/TimeRange", "description": "Time range for the beginning of the reporting period. Inclusive.\nDefault value: The current time minus one day.\nNote that `TerminalAction`s are available for 30 days after creation.", "readOnly": false, "required": false }, { "name": "status", "type": "string", "description": "Filter results with the desired status of the `TerminalAction`\nOptions: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, `COMPLETED`", "readOnly": false, "required": false }, { "name": "type", "type": "#/components/schemas/TerminalActionActionType", "description": "Filter results with the requested ActionType.\n", "readOnly": false, "required": false } ] }, { "name": "TimeRange", "properties": [ { "name": "start_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nstarts.", "readOnly": false, "required": false }, { "name": "end_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nends.", "readOnly": false, "required": false } ] }, { "name": "TerminalActionActionType", "properties": [] }, { "name": "TerminalActionQuerySort", "properties": [ { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "The order in which results are listed.\n- `ASC` - Oldest to newest.\n- `DESC` - Newest to oldest (default).\n", "readOnly": false, "required": false } ] }, { "name": "SortOrder", "properties": [] } ], "GetTerminalActionRequest": [ { "name": "GetTerminalActionRequest", "properties": [ { "name": "action_id", "type": "string", "description": "Unique ID for the desired `TerminalAction`.", "readOnly": false, "required": true } ] } ], "CancelTerminalActionRequest": [ { "name": "CancelTerminalActionRequest", "properties": [ { "name": "action_id", "type": "string", "description": "Unique ID for the desired `TerminalAction`.", "readOnly": false, "required": true } ] } ], "DismissTerminalActionRequest": [ { "name": "DismissTerminalActionRequest", "properties": [ { "name": "action_id", "type": "string", "description": "Unique ID for the `TerminalAction` associated with the action to be dismissed.", "readOnly": false, "required": true } ] } ], "CreateTerminalCheckoutRequest": [ { "name": "CreateTerminalCheckoutRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `CreateCheckout` request. Keys can be any valid string but\nmust be unique for every `CreateCheckout` request.\n\nSee [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information.", "readOnly": false, "required": true }, { "name": "checkout", "type": "#/components/schemas/TerminalCheckout", "description": "The checkout to create.", "readOnly": false, "required": true } ] }, { "name": "TerminalCheckout", "properties": [ { "name": "id", "type": "string", "description": "A unique ID for this `TerminalCheckout`.", "readOnly": true, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money (including the tax amount) that the Square Terminal device should try to collect.", "readOnly": false, "required": true }, { "name": "reference_id", "type": "string", "description": "An optional user-defined reference ID that can be used to associate\nthis `TerminalCheckout` to another entity in an external system. For example, an order\nID generated by a third-party shopping cart. The ID is also associated with any payments\nused to complete the checkout.", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "An optional note to associate with the checkout, as well as with any payments used to complete the checkout.\nNote: maximum 500 characters", "readOnly": false, "required": false }, { "name": "order_id", "type": "string", "description": "The reference to the Square order ID for the checkout request.", "readOnly": false, "required": false }, { "name": "payment_options", "type": "#/components/schemas/PaymentOptions", "description": "Payment-specific options for the checkout request. Supported only in the US.", "readOnly": false, "required": false }, { "name": "device_options", "type": "#/components/schemas/DeviceCheckoutOptions", "description": "Options to control the display and behavior of the Square Terminal device.", "readOnly": false, "required": true }, { "name": "deadline_duration", "type": "string", "description": "An RFC 3339 duration, after which the checkout is automatically canceled.\nA `TerminalCheckout` that is `PENDING` is automatically `CANCELED` and has a cancellation reason\nof `TIMED_OUT`.\n\nDefault: 5 minutes from creation\n\nMaximum: 5 minutes\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "status", "type": "string", "description": "The status of the `TerminalCheckout`.\nOptions: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, `COMPLETED`", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "#/components/schemas/ActionCancelReason", "description": "The reason why `TerminalCheckout` is canceled. Present if the status is `CANCELED`.\n", "readOnly": true, "required": false }, { "name": "payment_ids", "type": "array", "description": "A list of IDs for payments created by this `TerminalCheckout`.", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The time when the `TerminalCheckout` was created, as an RFC 3339 timestamp.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The time when the `TerminalCheckout` was last updated, as an RFC 3339 timestamp.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "app_id", "type": "string", "description": "The ID of the application that created the checkout.", "readOnly": true, "required": false }, { "name": "location_id", "type": "string", "description": "The location of the device where the `TerminalCheckout` was directed.", "readOnly": true, "required": false }, { "name": "payment_type", "type": "#/components/schemas/CheckoutOptionsPaymentType", "description": "The type of payment the terminal should attempt to capture from. Defaults to `CARD_PRESENT`.\n", "readOnly": false, "required": false }, { "name": "team_member_id", "type": "string", "description": "An optional ID of the team member associated with creating the checkout.", "readOnly": false, "required": false }, { "name": "customer_id", "type": "string", "description": "An optional ID of the customer associated with the checkout.", "readOnly": false, "required": false }, { "name": "app_fee_money", "type": "#/components/schemas/Money", "description": "The amount the developer is taking as a fee for facilitating the payment on behalf\nof the seller.\n\nThe amount cannot be more than 90% of the total amount of the payment.\n\nThe amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).\n\nThe fee currency code must match the currency associated with the seller that is accepting the payment. The application must be from a developer account in the same country and using the same currency code as the seller.\n\nFor more information about the application fee scenario, see [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).\n\nTo set this field, PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission is required. For more information, see [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).\n\nSupported only in the US.", "readOnly": false, "required": false }, { "name": "statement_description_identifier", "type": "string", "description": "Optional additional payment information to include on the customer's card statement as\npart of the statement description. This can be, for example, an invoice number, ticket number,\nor short description that uniquely identifies the purchase. Supported only in the US.", "readOnly": false, "required": false }, { "name": "tip_money", "type": "#/components/schemas/Money", "description": "The amount designated as a tip, in addition to `amount_money`. This may only be set for a\ncheckout that has tipping disabled (`tip_settings.allow_tipping` is `false`). Supported only in\nthe US.", "readOnly": false, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "PaymentOptions", "properties": [ { "name": "autocomplete", "type": "boolean", "description": "Indicates whether the `Payment` objects created from this `TerminalCheckout` are automatically\n`COMPLETED` or left in an `APPROVED` state for later modification.\n\nDefault: true", "readOnly": false, "required": false }, { "name": "delay_duration", "type": "string", "description": "The duration of time after the payment's creation when Square automatically resolves the\npayment. This automatic resolution applies only to payments that do not reach a terminal state\n(`COMPLETED` or `CANCELED`) before the `delay_duration` time period.\n\nThis parameter should be specified as a time duration, in RFC 3339 format, with a minimum value\nof 1 minute and a maximum value of 36 hours. This feature is only supported for card payments,\nand all payments will be considered card-present.\n\nThis parameter can only be set for a delayed capture payment (`autocomplete=false`). For more\ninformation, see [Delayed Capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).\n\nDefault: \"PT36H\" (36 hours) from the creation time\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "accept_partial_authorization", "type": "boolean", "description": "If set to `true` and charging a Square Gift Card, a payment might be returned with\n`amount_money` equal to less than what was requested. For example, a request for $20 when charging\na Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose\nto prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card\npayment.\n\nThis parameter can only be set for a delayed capture payment (`autocomplete=false`).\n\nFor more information, see [Take Partial Payments](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/partial-payments-with-gift-cards).\n\nDefault: false", "readOnly": false, "required": false }, { "name": "delay_action", "type": "#/components/schemas/PaymentOptionsDelayAction", "description": "The action to be applied to the `Payment` when the delay_duration has elapsed.\nThe action must be CANCEL or COMPLETE.\n\nThe action cannot be set to COMPLETE if an `order_id` is present on the TerminalCheckout.\n\nThis parameter can only be set for a delayed capture payment (`autocomplete=false`). For more\ninformation, see [Delayed Capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).\n\nDefault: CANCEL\n", "readOnly": false, "required": false } ] }, { "name": "PaymentOptionsDelayAction", "properties": [] }, { "name": "DeviceCheckoutOptions", "properties": [ { "name": "device_id", "type": "string", "description": "The unique ID of the device intended for this `TerminalCheckout`.\nA list of `DeviceCode` objects can be retrieved from the /v2/devices/codes endpoint.\nMatch a `DeviceCode.device_id` value with `device_id` to get the associated device code.", "readOnly": false, "required": true }, { "name": "skip_receipt_screen", "type": "boolean", "description": "Instructs the device to skip the receipt screen. Defaults to false.", "readOnly": false, "required": false }, { "name": "collect_signature", "type": "boolean", "description": "Indicates that signature collection is desired during checkout. Defaults to false.", "readOnly": false, "required": false }, { "name": "tip_settings", "type": "#/components/schemas/TipSettings", "description": "Tip-specific settings.", "readOnly": false, "required": false }, { "name": "show_itemized_cart", "type": "boolean", "description": "Show the itemization screen prior to taking a payment. This field is only meaningful when the\ncheckout includes an order ID. Defaults to true.", "readOnly": false, "required": false } ] }, { "name": "TipSettings", "properties": [ { "name": "allow_tipping", "type": "boolean", "description": "Indicates whether tipping is enabled for this checkout. Defaults to false.", "readOnly": false, "required": false }, { "name": "separate_tip_screen", "type": "boolean", "description": "Indicates whether tip options should be presented on the screen before presenting\nthe signature screen during card payment. Defaults to false.", "readOnly": false, "required": false }, { "name": "custom_tip_field", "type": "boolean", "description": "Indicates whether custom tip amounts are allowed during the checkout flow. Defaults to false.", "readOnly": false, "required": false }, { "name": "tip_percentages", "type": "array", "description": "A list of tip percentages that should be presented during the checkout flow, specified as\nup to 3 non-negative integers from 0 to 100 (inclusive). Defaults to 15, 20, and 25.", "readOnly": false, "required": false }, { "name": "smart_tipping", "type": "boolean", "description": "Enables the \"Smart Tip Amounts\" behavior.\nExact tipping options depend on the region in which the Square seller is active.\n\nFor payments under 10.00, in the Australia, Canada, Ireland, United Kingdom, and United States, tipping options are presented as no tip, .50, 1.00 or 2.00.\n\nFor payment amounts of 10.00 or greater, tipping options are presented as the following percentages: 0%, 5%, 10%, 15%.\n\nIf set to true, the `tip_percentages` settings is ignored.\nDefaults to false.\n\nTo learn more about smart tipping, see [Accept Tips with the Square App](https://squareup.com/help/us/en/article/5069-accept-tips-with-the-square-app).", "readOnly": false, "required": false } ] }, { "name": "ActionCancelReason", "properties": [] }, { "name": "CheckoutOptionsPaymentType", "properties": [] } ], "SearchTerminalCheckoutsRequest": [ { "name": "SearchTerminalCheckoutsRequest", "properties": [ { "name": "query", "type": "#/components/schemas/TerminalCheckoutQuery", "description": "Queries Terminal checkouts based on given conditions and the sort order.\nLeaving these unset returns all checkouts with the default sort order.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.\nSee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "Limits the number of results returned for a single request.", "readOnly": false, "required": false } ] }, { "name": "TerminalCheckoutQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/TerminalCheckoutQueryFilter", "description": "Options for filtering returned `TerminalCheckout` objects.", "readOnly": false, "required": false }, { "name": "sort", "type": "#/components/schemas/TerminalCheckoutQuerySort", "description": "Option for sorting returned `TerminalCheckout` objects.", "readOnly": false, "required": false } ] }, { "name": "TerminalCheckoutQueryFilter", "properties": [ { "name": "device_id", "type": "string", "description": "The `TerminalCheckout` objects associated with a specific device. If no device is specified, then all\n`TerminalCheckout` objects for the merchant are displayed.", "readOnly": false, "required": false }, { "name": "created_at", "type": "#/components/schemas/TimeRange", "description": "The time range for the beginning of the reporting period, which is inclusive.\nDefault value: The current time minus one day.\nNote that `TerminalCheckout`s are available for 30 days after creation.", "readOnly": false, "required": false }, { "name": "status", "type": "string", "description": "Filtered results with the desired status of the `TerminalCheckout`.\nOptions: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, `COMPLETED`", "readOnly": false, "required": false } ] }, { "name": "TimeRange", "properties": [ { "name": "start_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nstarts.", "readOnly": false, "required": false }, { "name": "end_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nends.", "readOnly": false, "required": false } ] }, { "name": "TerminalCheckoutQuerySort", "properties": [ { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "The order in which results are listed.\nDefault: `DESC`\n", "readOnly": false, "required": false } ] }, { "name": "SortOrder", "properties": [] } ], "GetTerminalCheckoutRequest": [ { "name": "GetTerminalCheckoutRequest", "properties": [ { "name": "checkout_id", "type": "string", "description": "The unique ID for the desired `TerminalCheckout`.", "readOnly": false, "required": true } ] } ], "CancelTerminalCheckoutRequest": [ { "name": "CancelTerminalCheckoutRequest", "properties": [ { "name": "checkout_id", "type": "string", "description": "The unique ID for the desired `TerminalCheckout`.", "readOnly": false, "required": true } ] } ], "DismissTerminalCheckoutRequest": [ { "name": "DismissTerminalCheckoutRequest", "properties": [ { "name": "checkout_id", "type": "string", "description": "Unique ID for the `TerminalCheckout` associated with the checkout to be dismissed.", "readOnly": false, "required": true } ] } ], "CreateTerminalRefundRequest": [ { "name": "CreateTerminalRefundRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies this `CreateRefund` request. Keys can be any valid string but\nmust be unique for every `CreateRefund` request.\n\nSee [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information.", "readOnly": false, "required": true }, { "name": "refund", "type": "#/components/schemas/TerminalRefund", "description": "The refund to create.", "readOnly": false, "required": false } ] }, { "name": "TerminalRefund", "properties": [ { "name": "id", "type": "string", "description": "A unique ID for this `TerminalRefund`.", "readOnly": true, "required": false }, { "name": "refund_id", "type": "string", "description": "The reference to the payment refund created by completing this `TerminalRefund`.", "readOnly": true, "required": false }, { "name": "payment_id", "type": "string", "description": "The unique ID of the payment being refunded.", "readOnly": false, "required": true }, { "name": "order_id", "type": "string", "description": "The reference to the Square order ID for the payment identified by the `payment_id`.", "readOnly": true, "required": false }, { "name": "amount_money", "type": "#/components/schemas/Money", "description": "The amount of money, inclusive of `tax_money`, that the `TerminalRefund` should return.\nThis value is limited to the amount taken in the original payment minus any completed or\npending refunds.", "readOnly": false, "required": true }, { "name": "reason", "type": "string", "description": "A description of the reason for the refund.", "readOnly": false, "required": true }, { "name": "device_id", "type": "string", "description": "The unique ID of the device intended for this `TerminalRefund`.\nThe Id can be retrieved from /v2/devices api.", "readOnly": false, "required": true }, { "name": "deadline_duration", "type": "string", "description": "The RFC 3339 duration, after which the refund is automatically canceled.\nA `TerminalRefund` that is `PENDING` is automatically `CANCELED` and has a cancellation reason\nof `TIMED_OUT`.\n\nDefault: 5 minutes from creation.\n\nMaximum: 5 minutes\n\nExample for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S", "readOnly": false, "required": false }, { "name": "status", "type": "string", "description": "The status of the `TerminalRefund`.\nOptions: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, or `COMPLETED`.", "readOnly": true, "required": false }, { "name": "cancel_reason", "type": "#/components/schemas/ActionCancelReason", "description": "Present if the status is `CANCELED`.\n", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The time when the `TerminalRefund` was created, as an RFC 3339 timestamp.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The time when the `TerminalRefund` was last updated, as an RFC 3339 timestamp.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "app_id", "type": "string", "description": "The ID of the application that created the refund.", "readOnly": true, "required": false }, { "name": "location_id", "type": "string", "description": "The location of the device where the `TerminalRefund` was directed.", "readOnly": true, "required": false } ] }, { "name": "Money", "properties": [ { "name": "amount", "type": "integer", "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "readOnly": false, "required": false }, { "name": "currency", "type": "#/components/schemas/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\n\n", "readOnly": false, "required": false } ] }, { "name": "Currency", "properties": [] }, { "name": "ActionCancelReason", "properties": [] } ], "SearchTerminalRefundsRequest": [ { "name": "SearchTerminalRefundsRequest", "properties": [ { "name": "query", "type": "#/components/schemas/TerminalRefundQuery", "description": "Queries the Terminal refunds based on given conditions and the sort order. Calling\n`SearchTerminalRefunds` without an explicit query parameter returns all available\nrefunds with the default sort order.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this cursor to retrieve the next set of results for the original query.", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "Limits the number of results returned for a single request.", "readOnly": false, "required": false } ] }, { "name": "TerminalRefundQuery", "properties": [ { "name": "filter", "type": "#/components/schemas/TerminalRefundQueryFilter", "description": "The filter for the Terminal refund query.", "readOnly": false, "required": false }, { "name": "sort", "type": "#/components/schemas/TerminalRefundQuerySort", "description": "The sort order for the Terminal refund query.", "readOnly": false, "required": false } ] }, { "name": "TerminalRefundQueryFilter", "properties": [ { "name": "device_id", "type": "string", "description": "`TerminalRefund` objects associated with a specific device. If no device is specified, then all\n`TerminalRefund` objects for the signed-in account are displayed.", "readOnly": false, "required": false }, { "name": "created_at", "type": "#/components/schemas/TimeRange", "description": "The timestamp for the beginning of the reporting period, in RFC 3339 format. Inclusive.\nDefault value: The current time minus one day.\nNote that `TerminalRefund`s are available for 30 days after creation.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": false, "required": false }, { "name": "status", "type": "string", "description": "Filtered results with the desired status of the `TerminalRefund`.\nOptions: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, or `COMPLETED`.", "readOnly": false, "required": false } ] }, { "name": "TimeRange", "properties": [ { "name": "start_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nstarts.", "readOnly": false, "required": false }, { "name": "end_at", "type": "string", "description": "A datetime value in RFC 3339 format indicating when the time range\nends.", "readOnly": false, "required": false } ] }, { "name": "TerminalRefundQuerySort", "properties": [ { "name": "sort_order", "type": "string", "description": "The order in which results are listed.\n- `ASC` - Oldest to newest.\n- `DESC` - Newest to oldest (default).", "readOnly": false, "required": false } ] } ], "GetTerminalRefundRequest": [ { "name": "GetTerminalRefundRequest", "properties": [ { "name": "terminal_refund_id", "type": "string", "description": "The unique ID for the desired `TerminalRefund`.", "readOnly": false, "required": true } ] } ], "CancelTerminalRefundRequest": [ { "name": "CancelTerminalRefundRequest", "properties": [ { "name": "terminal_refund_id", "type": "string", "description": "The unique ID for the desired `TerminalRefund`.", "readOnly": false, "required": true } ] } ], "DismissTerminalRefundRequest": [ { "name": "DismissTerminalRefundRequest", "properties": [ { "name": "terminal_refund_id", "type": "string", "description": "Unique ID for the `TerminalRefund` associated with the refund to be dismissed.", "readOnly": false, "required": true } ] } ], "BulkCreateVendorsRequest": [ { "name": "BulkCreateVendorsRequest", "properties": [ { "name": "vendors", "type": "map", "description": "Specifies a set of new [Vendor](entity:Vendor) objects as represented by a collection of idempotency-key/`Vendor`-object pairs.", "readOnly": false, "required": true } ] } ], "BulkRetrieveVendorsRequest": [ { "name": "BulkRetrieveVendorsRequest", "properties": [ { "name": "vendor_ids", "type": "array", "description": "IDs of the [Vendor](entity:Vendor) objects to retrieve.", "readOnly": false, "required": false } ] } ], "BulkUpdateVendorsRequest": [ { "name": "BulkUpdateVendorsRequest", "properties": [ { "name": "vendors", "type": "map", "description": "A set of [UpdateVendorRequest](entity:UpdateVendorRequest) objects encapsulating to-be-updated [Vendor](entity:Vendor)\nobjects. The set is represented by a collection of `Vendor`-ID/`UpdateVendorRequest`-object pairs.", "readOnly": false, "required": true } ] } ], "CreateVendorRequest": [ { "name": "CreateVendorRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A client-supplied, universally unique identifier (UUID) to make this [CreateVendor](api-endpoint:Vendors-CreateVendor) call idempotent.\n\nSee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the\n[API Development 101](https://developer.squareup.com/docs/buildbasics) section for more\ninformation.", "readOnly": false, "required": true }, { "name": "vendor", "type": "#/components/schemas/Vendor", "description": "The requested [Vendor](entity:Vendor) to be created.", "readOnly": false, "required": false } ] }, { "name": "Vendor", "properties": [ { "name": "id", "type": "string", "description": "A unique Square-generated ID for the [Vendor](entity:Vendor).\nThis field is required when attempting to update a [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "An RFC 3339-formatted timestamp that indicates when the\n[Vendor](entity:Vendor) was created.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "An RFC 3339-formatted timestamp that indicates when the\n[Vendor](entity:Vendor) was last updated.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "name", "type": "string", "description": "The name of the [Vendor](entity:Vendor).\nThis field is required when attempting to create or update a [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The address of the [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "contacts", "type": "array", "description": "The contacts of the [Vendor](entity:Vendor).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/VendorContact" }, { "name": "account_number", "type": "string", "description": "The account number of the [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "A note detailing information about the [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The version of the [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/VendorStatus", "description": "The status of the [Vendor](entity:Vendor).\n", "readOnly": false, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "VendorContact", "properties": [ { "name": "id", "type": "string", "description": "A unique Square-generated ID for the [VendorContact](entity:VendorContact).\nThis field is required when attempting to update a [VendorContact](entity:VendorContact).", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the [VendorContact](entity:VendorContact).\nThis field is required when attempting to create a [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "email_address", "type": "string", "description": "The email address of the [VendorContact](entity:VendorContact).", "readOnly": false, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number of the [VendorContact](entity:VendorContact).", "readOnly": false, "required": false }, { "name": "removed", "type": "boolean", "description": "The state of the [VendorContact](entity:VendorContact).", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The ordinal of the [VendorContact](entity:VendorContact).", "readOnly": false, "required": true } ] }, { "name": "VendorStatus", "properties": [] } ], "SearchVendorsRequest": [ { "name": "SearchVendorsRequest", "properties": [ { "name": "filter", "type": "#/components/schemas/SearchVendorsRequestFilter", "description": "Specifies a filter used to search for vendors.", "readOnly": false, "required": false }, { "name": "sort", "type": "#/components/schemas/SearchVendorsRequestSort", "description": "Specifies a sorter used to sort the returned vendors.", "readOnly": false, "required": false }, { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for the original query.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.", "readOnly": false, "required": false } ] }, { "name": "SearchVendorsRequestFilter", "properties": [ { "name": "name", "type": "array", "description": "The names of the [Vendor](entity:Vendor) objects to retrieve.", "readOnly": false, "required": false }, { "name": "status", "type": "array", "description": "The statuses of the [Vendor](entity:Vendor) objects to retrieve.\n", "readOnly": false, "required": false, "arrayType": "#/components/schemas/VendorStatus" } ] }, { "name": "VendorStatus", "properties": [] }, { "name": "SearchVendorsRequestSort", "properties": [ { "name": "field", "type": "#/components/schemas/SearchVendorsRequestSortField", "description": "Specifies the sort key to sort the returned vendors.\n", "readOnly": false, "required": false }, { "name": "order", "type": "#/components/schemas/SortOrder", "description": "Specifies the sort order for the returned vendors.\n", "readOnly": false, "required": false } ] }, { "name": "SearchVendorsRequestSortField", "properties": [] }, { "name": "SortOrder", "properties": [] } ], "RetrieveVendorRequest": [ { "name": "RetrieveVendorRequest", "properties": [ { "name": "vendor_id", "type": "string", "description": "ID of the [Vendor](entity:Vendor) to retrieve.", "readOnly": false, "required": true } ] } ], "UpdateVendorRequest": [ { "name": "UpdateVendorRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A client-supplied, universally unique identifier (UUID) for the\nrequest.\n\nSee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the\n[API Development 101](https://developer.squareup.com/docs/buildbasics) section for more\ninformation.", "readOnly": false, "required": false }, { "name": "vendor", "type": "#/components/schemas/Vendor", "description": "The specified [Vendor](entity:Vendor) to be updated.", "readOnly": false, "required": true } ] }, { "name": "Vendor", "properties": [ { "name": "id", "type": "string", "description": "A unique Square-generated ID for the [Vendor](entity:Vendor).\nThis field is required when attempting to update a [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "created_at", "type": "string", "description": "An RFC 3339-formatted timestamp that indicates when the\n[Vendor](entity:Vendor) was created.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "An RFC 3339-formatted timestamp that indicates when the\n[Vendor](entity:Vendor) was last updated.\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "name", "type": "string", "description": "The name of the [Vendor](entity:Vendor).\nThis field is required when attempting to create or update a [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "address", "type": "#/components/schemas/Address", "description": "The address of the [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "contacts", "type": "array", "description": "The contacts of the [Vendor](entity:Vendor).", "readOnly": false, "required": false, "arrayType": "#/components/schemas/VendorContact" }, { "name": "account_number", "type": "string", "description": "The account number of the [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "note", "type": "string", "description": "A note detailing information about the [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "version", "type": "integer", "description": "The version of the [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "status", "type": "#/components/schemas/VendorStatus", "description": "The status of the [Vendor](entity:Vendor).\n", "readOnly": false, "required": false } ] }, { "name": "Address", "properties": [ { "name": "address_line_1", "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields).", "readOnly": false, "required": false }, { "name": "address_line_2", "type": "string", "description": "The second line of the address, if any.", "readOnly": false, "required": false }, { "name": "address_line_3", "type": "string", "description": "The third line of the address, if any.", "readOnly": false, "required": false }, { "name": "locality", "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "sublocality", "type": "string", "description": "A civil region within the address's `locality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_2", "type": "string", "description": "A civil region within the address's `sublocality`, if any.", "readOnly": false, "required": false }, { "name": "sublocality_3", "type": "string", "description": "A civil region within the address's `sublocality_2`, if any.", "readOnly": false, "required": false }, { "name": "administrative_district_level_1", "type": "string", "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "administrative_district_level_2", "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county.", "readOnly": false, "required": false }, { "name": "administrative_district_level_3", "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`,\nif any.", "readOnly": false, "required": false }, { "name": "postal_code", "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "readOnly": false, "required": false }, { "name": "country", "type": "#/components/schemas/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\n", "readOnly": false, "required": false }, { "name": "first_name", "type": "string", "description": "Optional first name when it's representing recipient.", "readOnly": false, "required": false }, { "name": "last_name", "type": "string", "description": "Optional last name when it's representing recipient.", "readOnly": false, "required": false } ] }, { "name": "Country", "properties": [] }, { "name": "VendorContact", "properties": [ { "name": "id", "type": "string", "description": "A unique Square-generated ID for the [VendorContact](entity:VendorContact).\nThis field is required when attempting to update a [VendorContact](entity:VendorContact).", "readOnly": false, "required": false }, { "name": "name", "type": "string", "description": "The name of the [VendorContact](entity:VendorContact).\nThis field is required when attempting to create a [Vendor](entity:Vendor).", "readOnly": false, "required": false }, { "name": "email_address", "type": "string", "description": "The email address of the [VendorContact](entity:VendorContact).", "readOnly": false, "required": false }, { "name": "phone_number", "type": "string", "description": "The phone number of the [VendorContact](entity:VendorContact).", "readOnly": false, "required": false }, { "name": "removed", "type": "boolean", "description": "The state of the [VendorContact](entity:VendorContact).", "readOnly": false, "required": false }, { "name": "ordinal", "type": "integer", "description": "The ordinal of the [VendorContact](entity:VendorContact).", "readOnly": false, "required": true } ] }, { "name": "VendorStatus", "properties": [] } ], "ListWebhookEventTypesRequest": [ { "name": "ListWebhookEventTypesRequest", "properties": [ { "name": "api_version", "type": "string", "description": "The API version for which to list event types. Setting this field overrides the default version used by the application.", "readOnly": false, "required": false } ] } ], "ListWebhookSubscriptionsRequest": [ { "name": "ListWebhookSubscriptionsRequest", "properties": [ { "name": "cursor", "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for your original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "readOnly": false, "required": false }, { "name": "include_disabled", "type": "boolean", "description": "Includes disabled [Subscription](entity:WebhookSubscription)s.\nBy default, all enabled [Subscription](entity:WebhookSubscription)s are returned.", "readOnly": false, "required": false }, { "name": "sort_order", "type": "#/components/schemas/SortOrder", "description": "Sorts the returned list by when the [Subscription](entity:WebhookSubscription) was created with the specified order.\nThis field defaults to ASC.\n", "readOnly": false, "required": false }, { "name": "limit", "type": "integer", "description": "The maximum number of results to be returned in a single page.\nIt is possible to receive fewer results than the specified limit on a given page.\nThe default value of 100 is also the maximum allowed value.\n\nDefault: 100", "readOnly": false, "required": false } ] }, { "name": "SortOrder", "properties": [] } ], "CreateWebhookSubscriptionRequest": [ { "name": "CreateWebhookSubscriptionRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies the [CreateWebhookSubscription](api-endpoint:WebhookSubscriptions-CreateWebhookSubscription) request.", "readOnly": false, "required": false }, { "name": "subscription", "type": "#/components/schemas/WebhookSubscription", "description": "The [Subscription](entity:WebhookSubscription) to create.", "readOnly": false, "required": true } ] }, { "name": "WebhookSubscription", "properties": [ { "name": "id", "type": "string", "description": "A Square-generated unique ID for the subscription.", "readOnly": true, "required": false }, { "name": "name", "type": "string", "description": "The name of this subscription.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "Indicates whether the subscription is enabled (`true`) or not (`false`).", "readOnly": false, "required": false }, { "name": "event_types", "type": "array", "description": "The event types associated with this subscription.", "readOnly": false, "required": false }, { "name": "notification_url", "type": "string", "description": "The URL to which webhooks are sent.", "readOnly": false, "required": false }, { "name": "api_version", "type": "string", "description": "The API version of the subscription.\nThis field is optional for `CreateWebhookSubscription`. \nThe value defaults to the API version used by the application.", "readOnly": false, "required": false }, { "name": "signature_key", "type": "string", "description": "The Square-generated signature key used to validate the origin of the webhook event.", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp of when the subscription was created, in RFC 3339 format. For example, \"2016-09-04T23:59:33.123Z\".\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp of when the subscription was last updated, in RFC 3339 format.\nFor example, \"2016-09-04T23:59:33.123Z\".\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "DeleteWebhookSubscriptionRequest": [ { "name": "DeleteWebhookSubscriptionRequest", "properties": [ { "name": "subscription_id", "type": "string", "description": "[REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to delete.", "readOnly": false, "required": true } ] } ], "RetrieveWebhookSubscriptionRequest": [ { "name": "RetrieveWebhookSubscriptionRequest", "properties": [ { "name": "subscription_id", "type": "string", "description": "[REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to retrieve.", "readOnly": false, "required": true } ] } ], "UpdateWebhookSubscriptionRequest": [ { "name": "UpdateWebhookSubscriptionRequest", "properties": [ { "name": "subscription", "type": "#/components/schemas/WebhookSubscription", "description": "The [Subscription](entity:WebhookSubscription) to update.", "readOnly": false, "required": false }, { "name": "subscription_id", "type": "string", "description": "[REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to update.", "readOnly": false, "required": true } ] }, { "name": "WebhookSubscription", "properties": [ { "name": "id", "type": "string", "description": "A Square-generated unique ID for the subscription.", "readOnly": true, "required": false }, { "name": "name", "type": "string", "description": "The name of this subscription.", "readOnly": false, "required": false }, { "name": "enabled", "type": "boolean", "description": "Indicates whether the subscription is enabled (`true`) or not (`false`).", "readOnly": false, "required": false }, { "name": "event_types", "type": "array", "description": "The event types associated with this subscription.", "readOnly": false, "required": false }, { "name": "notification_url", "type": "string", "description": "The URL to which webhooks are sent.", "readOnly": false, "required": false }, { "name": "api_version", "type": "string", "description": "The API version of the subscription.\nThis field is optional for `CreateWebhookSubscription`. \nThe value defaults to the API version used by the application.", "readOnly": false, "required": false }, { "name": "signature_key", "type": "string", "description": "The Square-generated signature key used to validate the origin of the webhook event.", "readOnly": true, "required": false }, { "name": "created_at", "type": "string", "description": "The timestamp of when the subscription was created, in RFC 3339 format. For example, \"2016-09-04T23:59:33.123Z\".\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false }, { "name": "updated_at", "type": "string", "description": "The timestamp of when the subscription was last updated, in RFC 3339 format.\nFor example, \"2016-09-04T23:59:33.123Z\".\n\nExamples for January 25th, 2020 6:25:34pm Pacific Standard Time:\n\nUTC: 2020-01-26T02:25:34Z\n\nPacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00", "readOnly": true, "required": false } ] } ], "UpdateWebhookSubscriptionSignatureKeyRequest": [ { "name": "UpdateWebhookSubscriptionSignatureKeyRequest", "properties": [ { "name": "idempotency_key", "type": "string", "description": "A unique string that identifies the [UpdateWebhookSubscriptionSignatureKey](api-endpoint:WebhookSubscriptions-UpdateWebhookSubscriptionSignatureKey) request.", "readOnly": false, "required": false }, { "name": "subscription_id", "type": "string", "description": "[REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to update.", "readOnly": false, "required": true } ] } ], "TestWebhookSubscriptionRequest": [ { "name": "TestWebhookSubscriptionRequest", "properties": [ { "name": "event_type", "type": "string", "description": "The event type that will be used to test the [Subscription](entity:WebhookSubscription). The event type must be\ncontained in the list of event types in the [Subscription](entity:WebhookSubscription).", "readOnly": false, "required": false }, { "name": "subscription_id", "type": "string", "description": "[REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to test.", "readOnly": false, "required": true } ] } ] };