643 matches
100 actions
Square Connect
100 actions
Other/Square Connect
Creates a draft for an order created using the Orders API.
A draft invoice remains in your account and no action is taken. You must publish the invoice before Square can process it (send it to the customer's email address or charge the customer’s card on file).
{
"type": "object",
"description": "Describes a `CreateInvoice` request.",
"required": [
"invoice"
],
"properties": {
"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/working-with-apis/idempotency)."
},
"invoice": {
"type": "object",
"description": "Stores information about an invoice. You use the Invoices API to create and manage\ninvoices. For more information, see [Manage Invoices Using the Invoices API](https://developer.squareup.com/docs/invoices-api/overview).",
"properties": {
"accepted_payment_methods": {
"type": "object",
"description": "The payment methods that customers can use to pay an invoice on the Square-hosted invoice page.",
"properties": {
"bank_account": {
"type": "boolean",
"description": "Indicates whether bank transfer payments are accepted. The default value is `false`.\n\nThis option is allowed only for invoices that have a single payment request of type `BALANCE`."
},
"card": {
"type": "boolean",
"description": "Indicates whether credit card or debit card payments are accepted. The default value is `false`."
},
"square_gift_card": {
"type": "boolean",
"description": "Indicates whether Square gift card payments are accepted. The default value is `false`."
}
}
},
"created_at": {
"type": "string",
"description": "The timestamp when the invoice was created, in RFC 3339 format."
},
"custom_fields": {
"type": "array",
"description": "Additional seller-defined fields to render on the invoice. These fields are visible to sellers and buyers\non the Square-hosted invoice page and in emailed or PDF copies of invoices. 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",
"items": {
"type": "object",
"description": "An additional seller-defined and customer-facing field to include on the invoice. For more information, \nsee [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).",
"properties": {
"label": {
"type": "string",
"description": "The label or title of the custom field. This field is required for a custom field."
},
"placement": {
"type": "string",
"description": "The location of the custom field on the invoice. This field is required for a custom field."
},
"value": {
"type": "string",
"description": "The text of the custom field. If omitted, only the label is rendered."
}
}
}
},
"delivery_method": {
"type": "object"
},
"description": {
"type": "string",
"description": "The description of the invoice. This is visible to the customer receiving the invoice."
},
"id": {
"type": "string",
"description": "The Square-assigned ID of the invoice."
},
"invoice_number": {
"type": "string",
"description": "A user-friendly invoice number. The value is unique within a location.\nIf not provided when creating an invoice, Square assigns a value.\nIt increments from 1 and padded with zeros making it 7 characters long\n(for example, 0000001 and 0000002)."
},
"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."
},
"next_payment_amount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"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."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"order_id": {
"type": "string",
"description": "The ID of the [order](https://developer.squareup.com/reference/square_2021-08-18/objects/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](https://developer.squareup.com/reference/square_2021-08-18/orders-api/retrieve-order) endpoint using the order ID."
},
"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[Payment requests](https://developer.squareup.com/docs/invoices-api/overview#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).",
"items": {
"type": "object",
"description": "Represents a payment request for an [invoice](https://developer.squareup.com/reference/square_2021-08-18/objects/Invoice). Invoices can specify a maximum\nof 13 payment requests, with up to 12 `INSTALLMENT` request types. For more information, \nsee [Payment requests](https://developer.squareup.com/docs/invoices-api/overview#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).",
"properties": {
"automatic_payment_source": {
"type": "string",
"description": "The payment method for an automatic payment.\n\nThe default value is `NONE`."
},
"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](https://developer.squareup.com/reference/square_2021-08-18/cards-api/list-cards) and include the `customer_id` of the invoice recipient."
},
"computed_amount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"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."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"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.\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)."
},
"fixed_amount_requested_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"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."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"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."
},
"reminders": {
"type": "array",
"description": "A list of one or more reminders to send for the payment request.",
"items": {
"type": "object",
"description": "Describes a payment request reminder (automatic notification) that Square sends\nto the customer. You configure a reminder relative to the payment request\n`due_date`.",
"properties": {
"message": {
"type": "string",
"description": "The reminder message."
},
"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`."
},
"sent_at": {
"type": "string",
"description": "If sent, the timestamp when the reminder was sent, in RFC 3339 format."
},
"status": {
"type": "string",
"description": "The status of the reminder."
},
"uid": {
"type": "string",
"description": "A Square-assigned ID that uniquely identifies the reminder within the\n`InvoicePaymentRequest`."
}
}
}
},
"request_method": {
"type": "string",
"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`."
},
"request_type": {
"type": "string",
"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."
},
"rounding_adjustment_included_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"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."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"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`."
},
"total_completed_amount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"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."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"uid": {
"type": "string",
"description": "The Square-generated ID of the payment request in an [invoice](https://developer.squareup.com/reference/square_2021-08-18/objects/Invoice)."
}
}
}
},
"primary_recipient": {
"type": "object",
"description": "Provides customer data that Square uses to deliver an invoice.",
"properties": {
"address": {
"type": "object",
"description": "Represents a postal address in a country. The address format is based \non an [open-source library from Google](https://github.com/google/libaddressinput). For more information, \nsee [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata). \nThis format has dedicated fields for four address components: postal code, \nlocality (city), administrative district (state, prefecture, or province), and \nsublocality (town or village). These components have dedicated fields in the \n`Address` object because software sometimes behaves differently based on them. \nFor example, sales tax software may charge different amounts of sales tax \nbased on the postal code, and some software is only available in \ncertain states due to compliance reasons.\n\nFor the remaining address components, the `Address` type provides the \n`address_line_1` and `address_line_2` fields for free-form data entry. \nThese fields are free-form because the remaining address components have \ntoo many variations around the world and typical software does not parse \nthese components. These fields enable users to enter anything they want. \n\nNote that, in the current implementation, all other `Address` type fields are blank. \nThese include `address_line_3`, `sublocality_2`, `sublocality_3`, \n`administrative_district_level_2`, `administrative_district_level_3`, \n`first_name`, `last_name`, and `organization`. \n\nWhen it comes to localization, the seller's language preferences \n(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences)) \nare ignored for addresses. Even though Square products (such as Square Point of Sale \nand the Seller Dashboard) mostly use a seller's language preference in \ncommunication, when it comes to addresses, they will use English for a US address, \nJapanese for an address in Japan, and so on.",
"properties": {
"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)."
},
"address_line_2": {
"type": "string",
"description": "The second line of the address, if any."
},
"address_line_3": {
"type": "string",
"description": "The third line of the address, if any."
},
"administrative_district_level_1": {
"type": "string",
"description": "A civil entity within the address's country. In the US, this\nis the state."
},
"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."
},
"administrative_district_level_3": {
"type": "string",
"description": "A civil entity within the address's `administrative_district_level_2`,\nif any."
},
"country": {
"type": "string",
"description": "The address's country, in ISO 3166-1-alpha-2 format."
},
"first_name": {
"type": "string",
"description": "Optional first name when it's representing recipient."
},
"last_name": {
"type": "string",
"description": "Optional last name when it's representing recipient."
},
"locality": {
"type": "string",
"description": "The city or town of the address."
},
"organization": {
"type": "string",
"description": "Optional organization name when it's representing recipient."
},
"postal_code": {
"type": "string",
"description": "The address's postal code."
},
"sublocality": {
"type": "string",
"description": "A civil region within the address's `locality`, if any."
},
"sublocality_2": {
"type": "string",
"description": "A civil region within the address's `sublocality`, if any."
},
"sublocality_3": {
"type": "string",
"description": "A civil region within the address's `sublocality_2`, if any."
}
}
},
"company_name": {
"type": "string",
"description": "The name of the recipient's company."
},
"customer_id": {
"type": "string",
"description": "The ID of the customer. This is the customer profile ID that \nyou provide when creating a draft invoice."
},
"email_address": {
"type": "string",
"description": "The recipient's email address."
},
"family_name": {
"type": "string",
"description": "The recipient's family (that is, last) name."
},
"given_name": {
"type": "string",
"description": "The recipient's given (that is, first) name."
},
"phone_number": {
"type": "string",
"description": "The recipient's phone number."
}
}
},
"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."
},
"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."
},
"status": {
"type": "string",
"description": "The status of the invoice."
},
"subscription_id": {
"type": "string",
"description": "The ID of the [subscription](https://developer.squareup.com/reference/square_2021-08-18/objects/Subscription) associated with the invoice.\nThis field is present only on subscription billing invoices."
},
"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)."
},
"title": {
"type": "string",
"description": "The title of the invoice."
},
"updated_at": {
"type": "string",
"description": "The timestamp when the invoice was last updated, in RFC 3339 format."
},
"version": {
"type": "integer",
"description": "The Square-assigned version number, which is incremented each time an update is committed to the invoice."
}
}
}
}
}{
"type": "object",
"description": "The response returned by the `CreateInvoice` request.",
"properties": {
"errors": {
"type": "array",
"description": "Information about errors encountered during the request.",
"items": {
"type": "object",
"description": "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information.",
"required": [
"category",
"code"
],
"properties": {
"category": {
"type": "string",
"description": "The high-level category for the error."
},
"code": {
"type": "string",
"description": "The specific code of the error."
},
"detail": {
"type": "string",
"description": "A human-readable description of the error for debugging purposes."
},
"field": {
"type": "string",
"description": "The name of the field provided in the original request (if any) that\nthe error pertains to."
}
}
}
},
"invoice": {
"type": "object",
"description": "Stores information about an invoice. You use the Invoices API to create and manage\ninvoices. For more information, see [Manage Invoices Using the Invoices API](https://developer.squareup.com/docs/invoices-api/overview).",
"properties": {
"accepted_payment_methods": {
"type": "object",
"description": "The payment methods that customers can use to pay an invoice on the Square-hosted invoice page.",
"properties": {
"bank_account": {
"type": "boolean",
"description": "Indicates whether bank transfer payments are accepted. The default value is `false`.\n\nThis option is allowed only for invoices that have a single payment request of type `BALANCE`."
},
"card": {
"type": "boolean",
"description": "Indicates whether credit card or debit card payments are accepted. The default value is `false`."
},
"square_gift_card": {
"type": "boolean",
"description": "Indicates whether Square gift card payments are accepted. The default value is `false`."
}
}
},
"created_at": {
"type": "string",
"description": "The timestamp when the invoice was created, in RFC 3339 format."
},
"custom_fields": {
"type": "array",
"description": "Additional seller-defined fields to render on the invoice. These fields are visible to sellers and buyers\non the Square-hosted invoice page and in emailed or PDF copies of invoices. 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",
"items": {
"type": "object",
"description": "An additional seller-defined and customer-facing field to include on the invoice. For more information, \nsee [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).",
"properties": {
"label": {
"type": "string",
"description": "The label or title of the custom field. This field is required for a custom field."
},
"placement": {
"type": "string",
"description": "The location of the custom field on the invoice. This field is required for a custom field."
},
"value": {
"type": "string",
"description": "The text of the custom field. If omitted, only the label is rendered."
}
}
}
},
"delivery_method": {
"type": "object"
},
"description": {
"type": "string",
"description": "The description of the invoice. This is visible to the customer receiving the invoice."
},
"id": {
"type": "string",
"description": "The Square-assigned ID of the invoice."
},
"invoice_number": {
"type": "string",
"description": "A user-friendly invoice number. The value is unique within a location.\nIf not provided when creating an invoice, Square assigns a value.\nIt increments from 1 and padded with zeros making it 7 characters long\n(for example, 0000001 and 0000002)."
},
"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."
},
"next_payment_amount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"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."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"order_id": {
"type": "string",
"description": "The ID of the [order](https://developer.squareup.com/reference/square_2021-08-18/objects/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](https://developer.squareup.com/reference/square_2021-08-18/orders-api/retrieve-order) endpoint using the order ID."
},
"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[Payment requests](https://developer.squareup.com/docs/invoices-api/overview#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).",
"items": {
"type": "object",
"description": "Represents a payment request for an [invoice](https://developer.squareup.com/reference/square_2021-08-18/objects/Invoice). Invoices can specify a maximum\nof 13 payment requests, with up to 12 `INSTALLMENT` request types. For more information, \nsee [Payment requests](https://developer.squareup.com/docs/invoices-api/overview#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).",
"properties": {
"automatic_payment_source": {
"type": "string",
"description": "The payment method for an automatic payment.\n\nThe default value is `NONE`."
},
"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](https://developer.squareup.com/reference/square_2021-08-18/cards-api/list-cards) and include the `customer_id` of the invoice recipient."
},
"computed_amount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"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."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"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.\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)."
},
"fixed_amount_requested_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"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."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"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."
},
"reminders": {
"type": "array",
"description": "A list of one or more reminders to send for the payment request.",
"items": {
"type": "object",
"description": "Describes a payment request reminder (automatic notification) that Square sends\nto the customer. You configure a reminder relative to the payment request\n`due_date`.",
"properties": {
"message": {
"type": "string",
"description": "The reminder message."
},
"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`."
},
"sent_at": {
"type": "string",
"description": "If sent, the timestamp when the reminder was sent, in RFC 3339 format."
},
"status": {
"type": "string",
"description": "The status of the reminder."
},
"uid": {
"type": "string",
"description": "A Square-assigned ID that uniquely identifies the reminder within the\n`InvoicePaymentRequest`."
}
}
}
},
"request_method": {
"type": "string",
"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`."
},
"request_type": {
"type": "string",
"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."
},
"rounding_adjustment_included_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"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."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"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`."
},
"total_completed_amount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"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."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"uid": {
"type": "string",
"description": "The Square-generated ID of the payment request in an [invoice](https://developer.squareup.com/reference/square_2021-08-18/objects/Invoice)."
}
}
}
},
"primary_recipient": {
"type": "object",
"description": "Provides customer data that Square uses to deliver an invoice.",
"properties": {
"address": {
"type": "object",
"description": "Represents a postal address in a country. The address format is based \non an [open-source library from Google](https://github.com/google/libaddressinput). For more information, \nsee [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata). \nThis format has dedicated fields for four address components: postal code, \nlocality (city), administrative district (state, prefecture, or province), and \nsublocality (town or village). These components have dedicated fields in the \n`Address` object because software sometimes behaves differently based on them. \nFor example, sales tax software may charge different amounts of sales tax \nbased on the postal code, and some software is only available in \ncertain states due to compliance reasons.\n\nFor the remaining address components, the `Address` type provides the \n`address_line_1` and `address_line_2` fields for free-form data entry. \nThese fields are free-form because the remaining address components have \ntoo many variations around the world and typical software does not parse \nthese components. These fields enable users to enter anything they want. \n\nNote that, in the current implementation, all other `Address` type fields are blank. \nThese include `address_line_3`, `sublocality_2`, `sublocality_3`, \n`administrative_district_level_2`, `administrative_district_level_3`, \n`first_name`, `last_name`, and `organization`. \n\nWhen it comes to localization, the seller's language preferences \n(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences)) \nare ignored for addresses. Even though Square products (such as Square Point of Sale \nand the Seller Dashboard) mostly use a seller's language preference in \ncommunication, when it comes to addresses, they will use English for a US address, \nJapanese for an address in Japan, and so on.",
"properties": {
"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)."
},
"address_line_2": {
"type": "string",
"description": "The second line of the address, if any."
},
"address_line_3": {
"type": "string",
"description": "The third line of the address, if any."
},
"administrative_district_level_1": {
"type": "string",
"description": "A civil entity within the address's country. In the US, this\nis the state."
},
"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."
},
"administrative_district_level_3": {
"type": "string",
"description": "A civil entity within the address's `administrative_district_level_2`,\nif any."
},
"country": {
"type": "string",
"description": "The address's country, in ISO 3166-1-alpha-2 format."
},
"first_name": {
"type": "string",
"description": "Optional first name when it's representing recipient."
},
"last_name": {
"type": "string",
"description": "Optional last name when it's representing recipient."
},
"locality": {
"type": "string",
"description": "The city or town of the address."
},
"organization": {
"type": "string",
"description": "Optional organization name when it's representing recipient."
},
"postal_code": {
"type": "string",
"description": "The address's postal code."
},
"sublocality": {
"type": "string",
"description": "A civil region within the address's `locality`, if any."
},
"sublocality_2": {
"type": "string",
"description": "A civil region within the address's `sublocality`, if any."
},
"sublocality_3": {
"type": "string",
"description": "A civil region within the address's `sublocality_2`, if any."
}
}
},
"company_name": {
"type": "string",
"description": "The name of the recipient's company."
},
"customer_id": {
"type": "string",
"description": "The ID of the customer. This is the customer profile ID that \nyou provide when creating a draft invoice."
},
"email_address": {
"type": "string",
"description": "The recipient's email address."
},
"family_name": {
"type": "string",
"description": "The recipient's family (that is, last) name."
},
"given_name": {
"type": "string",
"description": "The recipient's given (that is, first) name."
},
"phone_number": {
"type": "string",
"description": "The recipient's phone number."
}
}
},
"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."
},
"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."
},
"status": {
"type": "string",
"description": "The status of the invoice."
},
"subscription_id": {
"type": "string",
"description": "The ID of the [subscription](https://developer.squareup.com/reference/square_2021-08-18/objects/Subscription) associated with the invoice.\nThis field is present only on subscription billing invoices."
},
"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)."
},
"title": {
"type": "string",
"description": "The title of the invoice."
},
"updated_at": {
"type": "string",
"description": "The timestamp when the invoice was last updated, in RFC 3339 format."
},
"version": {
"type": "integer",
"description": "The Square-assigned version number, which is incremented each time an update is committed to the invoice."
}
}
}
}
}