Square Payments （獨立發行商）（預覽版）

Square 幫助數百萬賣家經營業務 - 從安全的信用卡處理到銷售點解決方案。此連接器包含下列端點的動作：付款、終端機、訂單、訂閱、發票、目錄、庫存和客戶。

此連接器適用於以下產品和區域：

服務	Class	Regions
副駕駛工作室	進階	除下列區域外的所有 Power Automate 區域： - 美國政府（GCC） - 美國政府（海灣合作委員會高中） - 由 21Vianet 營運的中國雲 - 美國國防部（DoD）
邏輯應用程式	標準	所有 Logic Apps 區域，但下列區域除外： - Azure Government 區域 - Azure 中國區域 - 美國國防部（DoD）
Power Apps	進階	除下列區域外的所有 Power Apps 區域： - 美國政府（GCC） - 美國政府（海灣合作委員會高中） - 由 21Vianet 營運的中國雲 - 美國國防部（DoD）
Power Automate（自動化服務）	進階	除下列區域外的所有 Power Automate 區域： - 美國政府（GCC） - 美國政府（海灣合作委員會高中） - 由 21Vianet 營運的中國雲 - 美國國防部（DoD）

連絡人
名稱	特洛伊·泰勒
URL	https://www.hitachisolutions.com
Email	ttaylor@hitachisolutions.com

連接器中繼資料
Publisher	特洛伊·泰勒
網站	https://squareup.com/
隱私策略	https://squareup.com/us/en/legal/general/privacy
類別	商;銷售和客戶關係管理

節流限制

名稱	呼叫	續約期間
每個連線的 API 呼叫	100	60 秒

動作

付款訂單（Beta 版）	使用一或多筆核准的付款支付訂單，或以總計 0 結算訂單。請求中列出的payment_ids總額必須等於訂單總額。總金額為 0 的訂單可以透過在請求中指定空的payment_ids陣列來標記為已付款。
停用卡片	停用卡片，防止任何進一步的更新或收費。允許禁用已經禁用的卡，但沒有效果。
列出付款	擷取提出請求的帳戶所收取的付款清單。結果最終是一致的，新的付款或付款變更可能需要幾秒鐘的時間才會出現。
列出付款退款	擷取提出請求之帳戶的退款清單。結果最終是一致的，新的退款或退款變更可能需要幾秒鐘才能顯示。
列出客戶	列出與 Square 帳戶相關聯的客戶設定檔。在正常操作條件下，新建立或更新的客戶設定檔可在 30 秒內用於清單操作。有時，新配置檔或更新配置檔的傳播可能需要接近一分鐘或更長時間，尤其是在網路事件和中斷期間。
列出客戶區隔	擷取企業的客戶群清單。
列出客戶群組	擷取企業的客戶群組清單。
列出爭議	傳回與特定帳戶相關聯的爭議清單。
列出爭議證據	傳回與爭議相關聯的證據清單。
列出發票	傳回指定位置的發票清單。
列出訂閱事件	列出特定訂閱的所有事件。
刪除客戶	從企業中刪除客戶設定檔。此作業也會取消檔案中任何相關聯的卡片的連結。
刪除客戶群組	刪除由group_id值所識別的客戶群組。
刪除爭議證據	從爭議中移除指定的證據。
刪除發票	刪除指定的發票。刪除發票時，關聯的訂單狀態會變更為 CANCELED。您只能刪除草稿發票（您無法刪除已發佈的發票，包括排程處理的發票）。
刪除目錄物件	根據提供的識別碼刪除單一 CatalogObject，並在回應中傳回一組成功刪除的識別碼。刪除是串聯事件，因此也會刪除目標物件的所有子項。例如，刪除 CatalogItem 也會刪除其所有 CatalogItemVariation 子系。
取得付款	擷取特定付款的詳細資料。
取得發票	依發票識別碼擷取發票。
取得終端機結帳	依checkout_id擷取終端機出庫要求。
取消付款	取消（作廢）付款。您可以使用此端點來取消狀態為「已核准」的付款。
取消發票	取消發票。賣方無法收取已取消發票的付款。
取消終端機結帳	如果要求的狀態允許，則取消終端機出庫要求。
取消航站樓退款	如果要求狀態允許，則透過退款要求 ID 取消 Interac 終端機退款要求。
取消訂閱	將canceled_date欄位設定為作用中計費期間的結尾。在此日期之後，狀態會從「作用中」變更為「已取消」。
完成付款	完成（捕獲）付款。預設情況下，付款設定為在建立後立即完成。
將群組新增至客戶	將群組成員資格新增至客戶。客戶由customer_id值識別，客戶群組由group_id值識別。
建立付款	使用提供的來源建立付款。您可以使用此端點向卡片（信用卡/簽帳金融卡或 Square 禮品卡）收費，或記錄賣家在 Square 之外收到的付款（來自買家的現金付款或外部實體代表賣家處理的付款）。
建立卡片	將存檔的卡片新增至現有商家。
建立客戶	為企業建立新客戶。
建立客戶群組	為企業建立新的客戶群組。
建立爭議辨識項文字	上傳文字以用作爭議挑戰的證據。
建立發票	為使用訂單API建立的訂單建立草稿發票。草稿發票仍保留在您的帳戶中，不會採取任何行動。您必須先發布發票，然後 Square 才能處理發票（將其發送到客戶的電子郵件地址或從客戶存檔的卡中扣款）。
建立終端機出庫	建立終端機結帳請求並將其傳送到指定的裝置，以收取請求金額的付款。
建立終端退款	建立退款請求，以退還在 Square Terminal 上完成的 Interac 付款。
建立訂單	建立新訂單，其中可以包含要購買的產品和要套用至購買的設定的相關資訊。
建立訂用帳戶	為客戶建立訂閱方案的訂閱。如果您在請求中提供了存檔的卡，Square 會向該卡收取訂閱費用。否則，Square 會向客戶的電子郵件地址開具帳單。訂閱會立即啟動，除非要求包含選用start_date。每個單獨的訂閱都與特定位置相關聯。
從客戶中移除群組	從客戶移除群組成員資格。客戶由customer_id值識別，客戶群組由group_id值識別。
批次刪除目錄物件	根據提供的目標識別碼清單刪除一組 CatalogItems，並在回應中傳回一組成功刪除的識別碼。
批次擷取庫存盤點	傳回所要求位置所提供 CatalogObjects 的目前計數。
批次擷取庫存變更	根據提供的篩選條件傳回歷史實體計數和調整。
批次擷取目錄物件	根據提供的 ID 傳回一組物件。集合中傳回的每個 CatalogItem 都包含其所有子資訊，包括：其所有 CatalogItemVariation 物件、其 CatalogModifierList 物件的參考，以及套用至它的任何 CatalogTax 物件的識別碼。
批次擷取訂單	依 ID 擷取一組訂單。如果指定的訂單 ID 不存在，則會忽略該 ID，而不是產生錯誤。
批次更新插入目錄物件	根據提供的物件清單建立或更新最多 10,000 個目標物件。目標物件會分組成批次，而每個批次都會以全有或全無的方式插入/更新。如果批次中的物件以某種方式格式錯誤，或違反資料庫限制，則包含該項目的整個批次將被忽略。不過，相同要求中的其他批次可能仍會成功。每個批次最多可包含 1,000 個物件，只要請求的物件總計數（項目、變化、修飾詞清單、折扣和稅金）不超過 10,000 個，就會依序處理批次。
批次變更庫存	將調整和盤點套用至提供的品項數量。成功時：傳回請求中參考的所有物件的目前計算計數。
接受爭議	接受爭議的損失。 Square 將爭議金額退還給持卡人，並將爭議狀態更新為已接受。 Square 從賣家的 Square 帳戶中扣除有爭議的金額。如果 Square 帳戶沒有足夠的資金，Square 會從相關的銀行帳戶中扣除。
提交證據	向持卡人的銀行提交證據。在提交證據之前，Square 會彙編所有可用的證據。這包括使用 CreateDisputeEvidenceFile 和 CreateDisputeEvidenceText 端點上傳的證據，以及 Square 自動提供的證據（如果可用）。
搜尋客戶	使用支援的查詢篩選器搜尋與Square帳戶相關聯的客戶設定檔。呼叫 SearchCustomers 而不使用任何明確查詢篩選器，會傳回根據given_name和family_name依字母順序排序的所有客戶設定檔。
搜尋發票	從篩選器中指定的位置搜尋發票。
搜尋目錄物件	透過比對支援的搜尋屬性值（不包括項目或項目變化的自訂屬性值）來搜尋任何類型的 CatalogObject，以針對一或多個指定的查詢篩選條件。
搜尋終端結帳	擷取由提出請求的帳戶所建立的終端機結帳請求的篩選清單。
搜尋終端退款	擷取由提出請求的賣方建立的 Interac Terminal 退款請求的過濾清單。
搜尋訂單	搜尋一或多個地點的所有訂單。訂單包括所有銷售、退貨和換貨，無論它們以何種方式或何時進入 Square 生態系統（例如銷售點、發票和 Connect API）。
搜尋訂用帳戶	搜尋訂閱。結果會依訂閱建立日期依時間順序排序。如果要求指定多個位置 ID，端點會依位置 ID 排序結果，然後依每個位置內的建立日期排序結果。如果查詢中未提供位置，則會搜尋所有位置。
擷取卡片	擷取特定卡片的詳細資料。
擷取客戶	傳回單一客戶的詳細資料。
擷取客戶區段	擷取特定客戶區段。
擷取客戶群組	擷取特定客戶群組。
擷取庫存實體盤點	傳回 InventoryPhysicalCount 物件，其中包含提供physical_count_id。
擷取庫存盤點	擷取一組指定位置中指定 CatalogObject 的目前計算庫存計數。
擷取庫存調整	傳回 InventoryAdjustment 物件，其中包含提供的adjustment_id。
擷取庫存轉移（Beta 版）	傳回 InventoryTransfer 物件以及提供的transfer_id。
擷取爭議	傳回特定爭議的詳細資料。
擷取爭議證據	傳回請求 URL 路徑中證據 ID 所指定的證據中繼資料。如果您想稍後參考，您必須保留上傳的證據副本。上傳證據後，您無法下載證據。
擷取目錄物件	根據提供的識別碼，將單一 CatalogItem 傳回為 CatalogObject。傳回的物件包含所有相關的 CatalogItem 資訊，包括：CatalogItemVariation 子系、其 CatalogModifierList 物件的參考，以及套用至它的任何 CatalogTax 物件的識別碼。
擷取訂單	依 ID 擷取訂單。
擷取訂閱	擷取訂用帳戶。
更新付款	將付款更新為「已核准」狀態。您可以使用此端點更新amount_money和tip_money。
更新客戶	更新客戶設定檔。若要變更屬性，請指定新值。若要移除屬性，請將值指定為空字串或空物件。
更新客戶群組	更新客戶群組。
更新插入目錄物件	建立或更新目標 CatalogObject。
更新發票	透過修改欄位、清除欄位或兩者來更新發票。
更新訂閱	更新訂閱。您可以設定、修改及清除訂閱欄位值。
更新項目修飾符清單	更新套用至目標 CatalogItem 的 CatalogModifierList 物件，而不需要對整個專案執行更新插入。
更新項目稅金	更新套用至目標 CatalogItem 的 CatalogTax 物件，而不需要對整個項目執行更新插入。
更新順序（Beta 版）	透過新增、取代或刪除欄位來更新未結訂單。狀態為「已完成」或「已取消」的訂單無法更新。
清單卡片	擷取提出要求的帳戶所擁有的卡片清單。
清單目錄	傳回 CatalogObjects 清單，其中包含目錄中一組所需類型的所有物件（例如，所有 CatalogItem 和 CatalogTax 物件）。 ListCatalog 不會傳回已刪除的目錄項目。
獲得付款退款	使用refund_id擷取特定退款。
獲得終端退款	依 ID 擷取 Interac 終端機退款物件。
發佈發票	發佈指定的草稿發票。發票發布後，Square 會根據發票配置進行跟進。例如，Square 將發票發送到客戶的電子郵件地址，向客戶存檔的卡收費，或者什麼都不做。 Square 也會在 Square 託管的帳單頁面上提供帳單。
目錄信息	擷取 Square Catalog API 的相關資訊，例如 BatchUpsertCatalogObjects 端點可以使用的批次大小限制。
繼續訂閱	繼續已停用的訂閱。
複製訂單（Beta）	透過複製現有訂單來建立處於 DRAFT 狀態的新訂單。新建立的訂單只有從原始訂單複製的核心欄位（例如明細項目、稅金和折扣）。
計算訂單（Beta）	可讓應用程式預覽訂單定價，而無需建立訂單。
註冊 Apple Pay 網域	啟用網域以與 Apple Pay on the Web 和 Square 搭配使用。 Apple 會在此網域上執行驗證，以確保已正確設定為已啟用 Apple Pay 的網域。
退款付款	退款付款。您可以退還全部付款金額或部分付款金額。您可以使用此端點來退還卡片付款，或記錄現金或外部付款的退款。
透過冪等金鑰取消付款	取消（作廢）請求中指定的冪等金鑰所識別的付款。當 CreatePayment 請求的狀態未知時，請使用此方法（例如，在您傳送 CreatePayment 請求之後，發生網路錯誤，而且您沒有收到回應）。在這種情況下，您可以指示 Square 使用此端點取消付款。在請求中，您提供與 CreatePayment 請求中要取消的相同冪等索引鍵。取消付款後，您可以再次提交 CreatePayment 請求。請注意，如果找不到具有指定冪等金鑰的付款，則不會採取任何動作，且端點會成功傳回。

付款訂單（Beta 版）

作業識別碼：: OrderPay

使用一或多筆核准的付款支付訂單，或以總計 0 結算訂單。請求中列出的payment_ids總額必須等於訂單總額。總金額為 0 的訂單可以透過在請求中指定空的payment_ids陣列來標記為已付款。

參數

名稱	機碼	必要	類型	Description
訂單編號	order_id	True	string	訂單的識別碼。
冪等金鑰	idempotency_key		string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
付款 ID	payment_ids		array of string

傳回

名稱	路徑	類型	Description
ID	order.id	string	Square 發行的唯一識別碼。
位置標識碼	order.location_id	string	位置的識別碼。
明細項目	order.line_items	array of object
UID	order.line_items.uid	string	Square 產生的 ID。
數量	order.line_items.quantity	string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
名稱	order.line_items.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
總數	order.line_items.base_price_money.amount	integer	金額。
貨幣	order.line_items.base_price_money.currency	string	貨幣。
總數	order.line_items.gross_sales_money.amount	integer	金額。
貨幣	order.line_items.gross_sales_money.currency	string	貨幣。
總數	order.line_items.total_tax_money.amount	integer	金額。
貨幣	order.line_items.total_tax_money.currency	string	貨幣。
總數	order.line_items.total_discount_money.amount	integer	金額。
貨幣	order.line_items.total_discount_money.currency	string	貨幣。
總數	order.line_items.total_money.amount	integer	金額。
貨幣	order.line_items.total_money.currency	string	貨幣。
創建於	order.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	order.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
版本	order.version	integer	此物件的目前版本。
總數	order.total_tax_money.amount	integer	金額。
貨幣	order.total_tax_money.currency	string	貨幣。
總數	order.total_discount_money.amount	integer	金額。
貨幣	order.total_discount_money.currency	string	貨幣。
總數	order.total_money.amount	integer	金額。
貨幣	order.total_money.currency	string	貨幣。
關閉時間	order.closed_at	string	關閉時間，以 ISO 8601 格式。
招標	order.tenders	array of object
ID	order.tenders.id	string	物件的識別碼
位置標識碼	order.tenders.location_id	string	接收此投標部分的收件人（商家除外）的位置 ID。
交易 ID	order.tenders.transaction_id	string	投標相關交易的 ID。
創建於	order.tenders.created_at	string	建立時的時間戳記，採用 RFC 3339 格式。
總數	order.tenders.amount_money.amount	integer	金額。
貨幣	order.tenders.amount_money.currency	string	貨幣。
類型	order.tenders.type	string	指出類型。
地位	order.tenders.card_details.status	string	信用卡付款的目前狀態（例如 AUTHORIZED 或 CAPTURED）
卡片品牌	order.tenders.card_details.card.card_brand	string	卡片的品牌。
last_4	order.tenders.card_details.card.last_4	string	卡號的最後 4 位數字。
到期月	order.tenders.card_details.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	order.tenders.card_details.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	order.tenders.card_details.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
報名方式	order.tenders.card_details.entry_method	string	用於輸入交易卡詳細信息的方法。
付款標識碼	order.tenders.payment_id	string	Square 產生的付款唯一 ID。
總數	order.total_service_charge_money.amount	integer	金額。
貨幣	order.total_service_charge_money.currency	string	貨幣。
總數	order.net_amounts.total_money.amount	integer	金額。
貨幣	order.net_amounts.total_money.currency	string	貨幣。
總數	order.net_amounts.tax_money.amount	integer	金額。
貨幣	order.net_amounts.tax_money.currency	string	貨幣。
總數	order.net_amounts.discount_money.amount	integer	金額。
貨幣	order.net_amounts.discount_money.currency	string	貨幣。
總數	order.net_amounts.tip_money.amount	integer	金額。
貨幣	order.net_amounts.tip_money.currency	string	貨幣。
總數	order.net_amounts.service_charge_money.amount	integer	金額。
貨幣	order.net_amounts.service_charge_money.currency	string	貨幣。
名稱	order.source.name	string	名稱。
State	order.state	string	目前的狀態。

停用卡片

作業識別碼：: CardDisable

停用卡片，防止任何進一步的更新或收費。允許禁用已經禁用的卡，但沒有效果。

參數

名稱	機碼	必要	類型	Description
卡片 ID	card_id	True	string	卡片的識別碼。

傳回

名稱	路徑	類型	Description
ID	card.id	string	Square 發行的唯一識別碼。
地址行 1	card.billing_address.address_line_1	string	地址的第一行。以address_line開頭的欄位提供地址最具體的詳細信息，例如街道號碼、街道名稱和建築物名稱。
地址行 2	card.billing_address.address_line_2	string	地址的第二行（如果有的話）。
地區	card.billing_address.locality	string	地址所在的城市或城鎮。
行政區一級	card.billing_address.administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	card.billing_address.postal_code	string	地址的郵遞區號。
國家	card.billing_address.country	string	地址的國家/地區，採用 ISO 3166-1-alpha-2 格式。
指紋	card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
垃圾箱	card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
卡片品牌	card.card_brand	string	卡片的品牌。
卡片類型	card.card_type	string	卡片的類型。
持卡人姓名	card.cardholder_name	string	持卡人的姓名。
客戶識別碼	card.customer_id	string	此物件代表客戶的 ID。
已啟用	card.enabled	boolean	是否啟用。
到期月	card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	card.exp_year	integer	卡片到期日期的四位數年份。
最後 4 名	card.last_4	string	卡號的最後 4 位數字。
預付費類型	card.prepaid_type	string	指示卡片是否預付。
參考標識碼	card.reference_id	string	選用的使用者定義參照 ID。
版本	card.version	integer	此物件的目前版本。

列出付款

作業識別碼：: PaymentList

擷取提出請求的帳戶所收取的付款清單。結果最終是一致的，新的付款或付款變更可能需要幾秒鐘的時間才會出現。

參數

名稱	機碼	類型	Description
開始時間	begin_time	string	opened_at上查詢的包含開始時間，採用 ISO 8601 格式。
結束時間	end_time	string	opened_at上查詢的獨佔結束日期，採用 ISO 8601 格式。
排序順序	sort_order	string	依照以指定順序建立卡片的時間來排序傳回的清單。
Cursor	cursor	string	先前呼叫此端點所傳回的分頁游標。
位置標識碼	location_id	string	您可以指定此選用篩選器，以僅擷取屬於特定位置的記錄。
總數	total	integer	付款total_money中的確切金額。
最後 4 名	last_4	string	支付卡的最後四位數字。
卡片品牌	card_brand	string	付款卡的品牌（例如 VISA）。
限制	limit	integer	回應中要傳回的數目上限。

傳回

名稱	路徑	類型	Description
付款	payments	array of object
ID	payments.id	string	Square 發行的唯一識別碼。
創建於	payments.created_at	string	ISO 8601 格式的事件時間。
更新於	payments.updated_at	string	RFC 3339 格式的上次修改時間戳記
總數	payments.amount_money.amount	integer	金額。
貨幣	payments.amount_money.currency	string	貨幣。
地位	payments.status	string	此物件的目前驗證狀態。
延遲持續時間	payments.delay_duration	string	建立付款後，Square 自動將delay_action套用至付款的持續時間。
來源類型	payments.source_type	string	此付款的來源類型。
地位	payments.card_details.status	string	卡片付款的目前狀態。狀態可以是 AUTHORIZED、CAPTURED、VOID 或 FAILED。
卡片品牌	payments.card_details.card.card_brand	string	卡片的品牌。
last_4	payments.card_details.card.last_4	string	卡號的最後 4 位數字。
到期月	payments.card_details.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	payments.card_details.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	payments.card_details.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
卡片類型	payments.card_details.card.card_type	string	卡片的類型。
預付費類型	payments.card_details.card.prepaid_type	string	指示卡片是否預付。
垃圾箱	payments.card_details.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）
報名方式	payments.card_details.entry_method	string	用於輸入卡詳細信息以進行付款的方法。該方法可以是 KEYED、SWIPED、EMV、ON_FILE 或 CONTACTLESS。
CVV 狀態	payments.card_details.cvv_status	string	從卡片驗證值（CVV）檢查傳回的狀態碼。代碼可以是CVV_ACCEPTED、CVV_REJECTED或CVV_NOT_CHECKED。
AVS 狀態	payments.card_details.avs_status	string	從地址驗證系統（AVS）檢查傳回的狀態碼。代碼可以是AVS_ACCEPTED、AVS_REJECTED或AVS_NOT_CHECKED。
驗證結果代碼	payments.card_details.auth_result_code	string	發卡機構傳回的狀態碼，描述付款的授權狀態。
報表說明	payments.card_details.statement_description	string	傳送至卡片網路的報表說明。
授權於	payments.card_details.card_payment_timeline.authorized_at	string	授權付款的時間戳記，採用 RFC 3339 格式。
捕獲於	payments.card_details.card_payment_timeline.captured_at	string	擷取付款的時間戳記，採用 RFC 3339 格式。
位置標識碼	payments.location_id	string	位置的識別碼。
訂單編號	payments.order_id	string	訂單的識別碼。
手續費	payments.processing_fee	array of object
有效於	payments.processing_fee.effective_at	string	費用生效的時間戳記，採用 RFC 3339 格式。
類型	payments.processing_fee.type	string	此物件的類型。
總數	payments.processing_fee.amount_money.amount	integer	金額。
貨幣	payments.processing_fee.amount_money.currency	string	貨幣。
備註	payments.note	string	與客戶設定檔相關聯的自訂附註。
總數	payments.total_money.amount	integer	金額。
貨幣	payments.total_money.currency	string	貨幣。
總數	payments.approved_money.amount	integer	金額。
貨幣	payments.approved_money.currency	string	貨幣。
收據號碼	payments.receipt_number	string	付款的收據號碼。如果取消付款，則會遺失此欄位。
收據網址	payments.receipt_url	string	付款收據的 URL。此欄位只會針對已完成的付款填入。
延遲作	payments.delay_action	string	delay_duration過後要套用至付款的動作。
延遲至	payments.delayed_until	string	自動套用delay_action時的唯讀時間戳記，採用 RFC 3339 格式。
團隊成員 ID	payments.team_member_id	string	與物件相關聯之小組成員的 TeamMember 物件 ID。
方形產品	payments.application_details.square_product	string	Square 產品，例如 Square 銷售點（POS）、Square 發票或 Square 虛擬終端機。
應用程式識別碼	payments.application_details.application_id	string	分配給應用程序的 Square ID 用於接受付款。應用程式開發人員可以使用此資訊來識別其應用程式處理的付款。例如，如果開發人員使用自訂應用程式來處理付款，則此欄位會包含來自開發人員儀表板的應用程式 ID。如果賣家使用 Square App Marketplace 應用程式來處理付款，則該欄位會包含對應的應用程式 ID。
版本令牌	payments.version_token	string	用於樂觀並發。此不透明權杖可識別 Payment 物件的特定版本。

列出付款退款

作業識別碼：: RefundList

擷取提出請求之帳戶的退款清單。結果最終是一致的，新的退款或退款變更可能需要幾秒鐘才能顯示。

參數

名稱	機碼	類型	Description
開始時間	begin_time	string	opened_at上查詢的包含開始時間，採用 ISO 8601 格式。
結束時間	end_time	string	opened_at上查詢的獨佔結束日期，採用 ISO 8601 格式。
排序順序	sort_order	string	依照以指定順序建立卡片的時間來排序傳回的清單。
Cursor	cursor	string	先前呼叫此端點所傳回的分頁游標。
位置標識碼	location_id	string	您可以指定此選用篩選器，以僅擷取屬於特定位置的記錄。
地位	status	string	如果指定，則只會傳回符合指定狀態的物件。
來源類型	source_type	string	如果提供，則只會傳回具有指定來源類型的退款。
限制	limit	integer	回應中要傳回的數目上限。

傳回

名稱	路徑	類型	Description
退款	refunds	array of object
ID	refunds.id	string	Square 發行的唯一識別碼。
地位	refunds.status	string	此物件的目前驗證狀態。
總數	refunds.amount_money.amount	integer	金額。
貨幣	refunds.amount_money.currency	string	貨幣。
付款標識碼	refunds.payment_id	string	付款的 ID。
訂單編號	refunds.order_id	string	訂單的識別碼。
創建於	refunds.created_at	string	ISO 8601 格式的事件時間。
更新於	refunds.updated_at	string	RFC 3339 格式的上次修改時間戳記
手續費	refunds.processing_fee	array of object
有效於	refunds.processing_fee.effective_at	string	費用生效的時間戳記，採用 RFC 3339 格式。
類型	refunds.processing_fee.type	string	此物件的類型。
總數	refunds.processing_fee.amount_money.amount	integer	金額。
貨幣	refunds.processing_fee.amount_money.currency	string	貨幣。
位置標識碼	refunds.location_id	string	位置的識別碼。
原因	refunds.reason	string	持卡人向銀行發起爭議的爭議原因。
Cursor	cursor	string	在此端點的後續呼叫中包含分頁游標，以擷取與原始查詢相關聯的下一組結果。

列出客戶

作業識別碼：: CustomerList

列出與 Square 帳戶相關聯的客戶設定檔。在正常操作條件下，新建立或更新的客戶設定檔可在 30 秒內用於清單操作。有時，新配置檔或更新配置檔的傳播可能需要接近一分鐘或更長時間，尤其是在網路事件和中斷期間。

參數

名稱	機碼	類型	Description
Cursor	cursor	string	先前呼叫此端點所傳回的分頁游標。
限制	limit	integer	回應中要傳回的數目上限。
排序欄位	sort_field	string	指出應如何排序客戶。預設值為 DEFAULT。
排序順序	sort_order	string	依照以指定順序建立卡片的時間來排序傳回的清單。

傳回

名稱	路徑	類型	Description
客戶	customers	array of object
ID	customers.id	string	Square 發行的唯一識別碼。
創建於	customers.created_at	string	ISO 8601 格式的事件時間。
更新於	customers.updated_at	string	RFC 3339 格式的上次修改時間戳記
名字	customers.given_name	string	與客戶設定檔相關聯的給定（即名字）名稱。
姓	customers.family_name	string	與客戶設定檔相關聯的家族（即姓氏）名稱。
電子郵件地址	customers.email_address	string	與客戶設定檔相關聯的電子郵件地址。
地址行 1	customers.address.address_line_1	string	地址的第一行。
地址行 2	customers.address.address_line_2	string	地址的第二行（如果有的話）。
地區	customers.address.locality	string	地址所在的城市或城鎮。
行政區一級	customers.address.administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	customers.address.postal_code	string	地址的郵遞區號。
國家	customers.address.country	string	地址的國家/地區，採用 ISO 3166-1-alpha-2 格式。
電話號碼	customers.phone_number	string	與客戶設定檔相關聯的 11 位電話號碼。
參考標識碼	customers.reference_id	string	選用的第二個 ID，用來將客戶設定檔與另一個系統中的實體建立關聯。
備註	customers.note	string	與客戶設定檔相關聯的自訂附註。
電子郵件取消訂閱	customers.preferences.email_unsubscribed	boolean	指出客戶是否已取消訂閱行銷活動電子郵件。值為 true 表示客戶選擇退出目前 Square 賣家或所有 Square 賣家的電子郵件行銷。此值是客戶 API 中的唯讀值。
創作來源	customers.creation_source	string	建立來源代表用來建立客戶設定檔的方法。
群組標識碼	customers.group_ids	array of string
區段ID	customers.segment_ids	array of string
版本	customers.version	integer	物件的目前版本。

列出客戶區隔

作業識別碼：: CustomerSegmentList

擷取企業的客戶群清單。

參數

名稱	機碼	必要	類型	Description
Cursor	cursor		string	先前呼叫此端點所傳回的分頁游標。
限制	limit		integer	回應中要傳回的數目上限。

傳回

名稱	路徑	類型	Description
段落	segments	array of object
ID	segments.id	string	Square 發行的唯一識別碼。
名稱	segments.name	string	物件的名稱。
創建於	segments.created_at	string	ISO 8601 格式的事件時間。
更新於	segments.updated_at	string	RFC 3339 格式的上次修改時間戳記

列出客戶群組

作業識別碼：: CustomerGroupList

擷取企業的客戶群組清單。

傳回

名稱	路徑	類型	Description
Groups	groups	array of object
ID	groups.id	string	Square 發行的唯一識別碼。
名稱	groups.name	string	物件的名稱。
創建於	groups.created_at	string	ISO 8601 格式的事件時間。
更新於	groups.updated_at	string	RFC 3339 格式的上次修改時間戳記

列出爭議

作業識別碼：: DisputeList

傳回與特定帳戶相關聯的爭議清單。

參數

名稱	機碼	類型	Description
Cursor	cursor	string	先前呼叫此端點所傳回的分頁游標。
States	states	string	爭議狀態是過濾結果。如果未指定，端點會傳回所有未解決的爭議（爭議狀態不是 INQUIRY_CLOSED、WEN 或 LOST）。
位置標識碼	location_id	string	您可以指定此選用篩選器，以僅擷取屬於特定位置的記錄。

傳回

名稱	路徑	類型	Description
爭議	disputes	array of object
ID	disputes.id	string	Square 發行的唯一識別碼。
總數	disputes.amount_money.amount	integer	金額。
貨幣	disputes.amount_money.currency	string	貨幣。
原因	disputes.reason	string	持卡人向銀行發起爭議的爭議原因。
State	disputes.state	string	目前的狀態。
到期日	disputes.due_at	string	下一個動作到期的時間，採用 RFC 3339 格式。
有爭議的付款	disputes.disputed_payments	array of object
付款標識碼	disputes.disputed_payments.payment_id	string	Square 產生的有爭議付款的唯一 ID。
卡片品牌	disputes.card_brand	string	有爭議的付款中使用的卡片品牌。
創建於	disputes.created_at	string	ISO 8601 格式的事件時間。
更新於	disputes.updated_at	string	RFC 3339 格式的上次修改時間戳記
品牌爭議編號	disputes.brand_dispute_id	string	卡片品牌系統中爭議的 ID，由卡片品牌產生。
Cursor	cursor	string	在此端點的後續呼叫中包含分頁游標，以擷取與原始查詢相關聯的下一組結果。

列出爭議證據

作業識別碼：: DisputeListEvidence

傳回與爭議相關聯的證據清單。

參數

名稱	機碼	必要	類型	Description
爭議 ID	dispute_id	True	string	爭議的標識符。

傳回

名稱	路徑	類型	Description
Evidence	evidence	array of object
ID	evidence.id	string	Square 發行的唯一識別碼。
爭議 ID	evidence.dispute_id	string	與證據相關聯的爭議 ID。
證據文本	evidence.evidence_text	string	原始文本。
辨識項類型	evidence.evidence_type	string	證據的類型。
上傳於	evidence.uploaded_at	string	下一個動作到期的時間，採用 RFC 3339 格式。
證據 ID	evidence.evidence_id	string	證據的 Square 產生的 ID。
檔名	evidence.evidence_file.filename	string	檔案名稱（包括副檔名）
檔案類型	evidence.evidence_file.filetype	string	爭議證據文件必須是 application/pdf、image/heic、image/heif、image/jpeg、image/png 或 image/tiff 格式。
Cursor	cursor	string	在此端點的後續呼叫中包含分頁游標，以擷取與原始查詢相關聯的下一組結果。

列出發票

作業識別碼：: InvoiceList

傳回指定位置的發票清單。

參數

名稱	機碼	類型	Description
位置標識碼	location_id	string	您可以指定此選用篩選器，以僅擷取屬於特定位置的記錄。
Cursor	cursor	string	先前呼叫此端點所傳回的分頁游標。
限制	limit	integer	回應中要傳回的數目上限。

傳回

名稱	路徑	類型	Description
Invoices	invoices	array of object
ID	invoices.id	string	Square 發行的唯一識別碼。
版本	invoices.version	integer	物件的目前版本。
位置標識碼	invoices.location_id	string	位置的識別碼。
訂單編號	invoices.order_id	string	訂單的識別碼。
付款請求	invoices.payment_requests	array of object
UID	invoices.payment_requests.uid	string	Square在發票中產生的付款請求ID。
請求類型	invoices.payment_requests.request_type	string	識別付款請求類型。此類型定義如何確定付款請求金額。
到期日	invoices.payment_requests.due_date	string	付款要求的到期日（以發票的時區為單位），格式為 YYYY-MM-DD。
啟用小費	invoices.payment_requests.tipping_enabled	boolean	如果設定為 true，則 Square 託管的帳單頁面（帳單的public_url欄位）會為顧客提供支付小費的位置。
溫馨提示	invoices.payment_requests.reminders	array of object	提醒
UID	invoices.payment_requests.reminders.uid	string	Square 指派的識別碼，可唯一識別 InvoicePaymentRequest 內的提醒。
相對排程天數	invoices.payment_requests.reminders.relative_scheduled_days	integer	付款請求之前（負數）或之後（正數）傳送提醒due_date的天數。
Message	invoices.payment_requests.reminders.message	string	提醒訊息。
地位	invoices.payment_requests.reminders.status	string	提醒的狀態。
總數	invoices.payment_requests.computed_amount_money.amount	integer	金額。
貨幣	invoices.payment_requests.computed_amount_money.currency	string	貨幣。
總數	invoices.payment_requests.total_completed_amount_money.amount	integer	金額。
貨幣	invoices.payment_requests.total_completed_amount_money.currency	string	貨幣。
自動付款來源	invoices.payment_requests.automatic_payment_source	string	自動付款的付款方式。
請求百分比	invoices.payment_requests.percentage_requested	string	以百分比指定付款請求的金額。
卡片 ID	invoices.payment_requests.card_id	string	存檔的信用卡或簽帳金融卡的 ID，用於收取付款要求。
發票號碼	invoices.invoice_number	string	用戶友好的發票號碼。
Title	invoices.title	string	發票的標題。
Description	invoices.description	string	描述。
預定時間	invoices.scheduled_at	string	排程處理發票的時間戳記，採用 RFC 3339 格式。發票發布後，Square 會根據交付方式和付款請求設置在指定日期處理發票。
地位	invoices.status	string	此物件的目前驗證狀態。
Timezone	invoices.timezone	string	用於解譯發票上行事曆日期的時區，例如due_date。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
創建於	invoices.created_at	string	ISO 8601 格式的事件時間。
更新於	invoices.updated_at	string	RFC 3339 格式的上次修改時間戳記
客戶識別碼	invoices.primary_recipient.customer_id	string	要與卡片相關聯的客戶 ID。
名字	invoices.primary_recipient.given_name	string	收件人的給定（即名字）。
姓	invoices.primary_recipient.family_name	string	收件者的姓氏（即姓氏）。
電子郵件地址	invoices.primary_recipient.email_address	string	收件者的電子郵件地址。
電話號碼	invoices.primary_recipient.phone_number	string	收件者的電話號碼。
Card	invoices.accepted_payment_methods.card	boolean	指出是否接受信用卡或簽帳金融卡付款。
Square 禮品卡	invoices.accepted_payment_methods.square_gift_card	boolean	指出是否接受 Square 禮品卡付款。
銀行帳戶	invoices.accepted_payment_methods.bank_account	boolean	指出是否接受銀行轉帳付款。
自訂欄位	invoices.custom_fields	array of object
標籤	invoices.custom_fields.label	string	自訂欄位的標籤或標題。
價值觀	invoices.custom_fields.value	string	自訂欄位的文字。
放置	invoices.custom_fields.placement	string	發票上自訂欄位的位置
送貨方式	invoices.delivery_method	string	Square 用來向顧客傳送發票、提醒和收據的配送方式。
銷售或服務日期	invoices.sale_or_service_date	string	銷售日期或提供服務的日期，以 YYYY-MM-DD 格式。此欄位可用來指定發票上顯示的過去或未來日期。
公用網址	invoices.public_url	string	Square 代管的帳單頁面的網址。使用 PublishInvoice 端點發佈發票後，Square 會託管發票頁面，並在回應中傳回頁面 URL。
總數	invoices.next_payment_amount_money.amount	integer	金額。
貨幣	invoices.next_payment_amount_money.currency	string	貨幣。
Cursor	cursor	string	在此端點的後續呼叫中包含分頁游標，以擷取與原始查詢相關聯的下一組結果。

列出訂閱事件

作業識別碼：: SubscriptionListEvents

列出特定訂閱的所有事件。

參數

名稱	機碼	必要	類型	Description
訂用帳戶識別碼	subscription_id	True	string	訂用帳戶的識別碼。

傳回

名稱	路徑	類型	Description
訂閱事件	subscription_events	array of object
ID	subscription_events.id	string	Square 發行的唯一識別碼。
訂閱事件類型	subscription_events.subscription_event_type	string	訂閱事件的類型。
生效日期	subscription_events.effective_date	string	訂閱事件生效的日期（YYYY-MM-DD 格式）。
方案標識碼	subscription_events.plan_id	string	相關聯訂閱方案的識別碼

刪除客戶

作業識別碼：: CustomerDelete

從企業中刪除客戶設定檔。此作業也會取消檔案中任何相關聯的卡片的連結。

參數

名稱	機碼	必要	類型	Description
客戶識別碼	customer_id	True	string	客戶的識別碼。

傳回

response: object

刪除客戶群組

作業識別碼：: CustomerGroupDelete

刪除由group_id值所識別的客戶群組。

參數

名稱	機碼	必要	類型	Description
群組識別碼	group_id	True	string	群組的識別碼。

傳回

response: object

刪除爭議證據

作業識別碼：: DisputeDeleteEvidence

從爭議中移除指定的證據。

參數

名稱	機碼	必要	類型	Description
爭議 ID	dispute_id	True	string	爭議的標識符。
證據 ID	evidence_id	True	string	證據的識別碼。

傳回

response: object

刪除發票

作業識別碼：: InvoiceDelete

刪除指定的發票。刪除發票時，關聯的訂單狀態會變更為 CANCELED。您只能刪除草稿發票（您無法刪除已發佈的發票，包括排程處理的發票）。

參數

名稱	機碼	必要	類型	Description
發票識別碼	invoice_id	True	string	發票的識別碼。
版本	version		integer	要刪除的發票版本。

傳回

response: object

刪除目錄物件

作業識別碼：: CatalogDelete

根據提供的識別碼刪除單一 CatalogObject，並在回應中傳回一組成功刪除的識別碼。刪除是串聯事件，因此也會刪除目標物件的所有子項。例如，刪除 CatalogItem 也會刪除其所有 CatalogItemVariation 子系。

參數

名稱	機碼	必要	類型	Description
物件識別碼	object_id	True	string	物件的識別碼。

傳回

名稱	路徑	類型	Description
已刪除的物件 ID	deleted_object_ids	array of string
刪除時間	deleted_at	string	此刪除的資料庫時間戳記，採用 RFC 3339 格式

取得付款

作業識別碼：: PaymentGet

擷取特定付款的詳細資料。

參數

名稱	機碼	必要	類型	Description
付款標識碼	payment_id	True	string	付款的識別碼。

傳回

名稱	路徑	類型	Description
ID	payment.id	string	Square 發行的唯一識別碼。
創建於	payment.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	payment.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
總數	payment.amount_money.amount	integer	金額。
貨幣	payment.amount_money.currency	string	貨幣。
地位	payment.status	string	此物件的目前驗證狀態。
延遲持續時間	payment.delay_duration	string	建立付款後，Square 自動將delay_action套用至付款的持續時間。此自動delay_action僅適用於在delay_duration時段之前未達到終止狀態（COMPLETED、CANCELED 或 FAILED）的付款。此欄位以 RFC 3339 格式指定為持續時間。
來源類型	payment.source_type	string	此付款的來源類型。目前值包括 CARD、BANK_ACCOUNT、WALLET、CASH 或 EXTERNAL。
地位	payment.card_details.status	string	目前狀態。
卡片品牌	payment.card_details.card.card_brand	string	卡片的品牌。
最後 4 名	payment.card_details.card.last_4	string	卡號的最後 4 位數字。
到期月	payment.card_details.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	payment.card_details.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	payment.card_details.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
卡片類型	payment.card_details.card.card_type	string	卡片的類型。
預付費類型	payment.card_details.card.prepaid_type	string	指示卡片是否預付。
垃圾箱	payment.card_details.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
報名方式	payment.card_details.entry_method	string	用於輸入卡詳細信息以進行付款的方法。該方法可以是 KEYED、SWIPED、EMV、ON_FILE 或 CONTACTLESS。
CVV 狀態	payment.card_details.cvv_status	string	從卡片驗證值（CVV）檢查傳回的狀態碼。代碼可以是CVV_ACCEPTED、CVV_REJECTED或CVV_NOT_CHECKED。
AVS 狀態	payment.card_details.avs_status	string	從地址驗證系統（AVS）檢查傳回的狀態碼。代碼可以是AVS_ACCEPTED、AVS_REJECTED或AVS_NOT_CHECKED。
驗證結果代碼	payment.card_details.auth_result_code	string	發卡機構傳回的狀態碼，描述付款的授權狀態。
報表說明	payment.card_details.statement_description	string	傳送至卡片網路的報表說明。
授權於	payment.card_details.card_payment_timeline.authorized_at	string	授權付款的時間戳記，採用 RFC 3339 格式。
捕獲於	payment.card_details.card_payment_timeline.captured_at	string	擷取付款的時間戳記，採用 RFC 3339 格式。
位置標識碼	payment.location_id	string	位置的識別碼。
訂單編號	payment.order_id	string	訂單的識別碼。
手續費	payment.processing_fee	array of object
有效於	payment.processing_fee.effective_at	string	費用生效的時間戳記，採用 RFC 3339 格式。
類型	payment.processing_fee.type	string	指出類型。
總數	payment.processing_fee.amount_money.amount	integer	金額。
貨幣	payment.processing_fee.amount_money.currency	string	貨幣。
備註	payment.note	string	與客戶設定檔相關聯的自訂附註。
總數	payment.total_money.amount	integer	金額。
貨幣	payment.total_money.currency	string	貨幣。
總數	payment.approved_money.amount	integer	金額。
貨幣	payment.approved_money.currency	string	貨幣。
員工 ID	payment.employee_id	string	員工的 Square 產生的 ID。
收據號碼	payment.receipt_number	string	付款的收據號碼。如果取消付款，則會遺失此欄位。
收據網址	payment.receipt_url	string	付款收據的 URL。此欄位只會針對已完成的付款填入。
延遲作	payment.delay_action	string	delay_duration過後要套用至付款的動作。
延遲至	payment.delayed_until	string	自動套用delay_action時的唯讀時間戳記，採用 RFC 3339 格式。
團隊成員 ID	payment.team_member_id	string	團隊成員的 ID。
方形產品	payment.application_details.square_product	string	Square 產品，例如 Square 銷售點（POS）、Square 發票或 Square 虛擬終端機。
應用程式識別碼	payment.application_details.application_id	string	指派給應用程式的唯讀 Square ID。
版本令牌	payment.version_token	string	此不透明權杖可識別物件的特定版本。

取得發票

作業識別碼：: InvoiceGet

依發票識別碼擷取發票。

參數

名稱	機碼	必要	類型	Description
發票識別碼	invoice_id	True	string	發票的識別碼。

傳回

名稱	路徑	類型	Description
ID	invoice.id	string	Square 發行的唯一識別碼。
版本	invoice.version	integer	此物件的目前版本。
位置標識碼	invoice.location_id	string	位置的識別碼。
訂單編號	invoice.order_id	string	訂單的識別碼。
付款請求	invoice.payment_requests	array of object
UID	invoice.payment_requests.uid	string	Square 產生的 ID。
請求類型	invoice.payment_requests.request_type	string	識別付款請求類型。此類型定義如何確定付款請求金額。
到期日	invoice.payment_requests.due_date	string	付款要求的到期日，以 YYYY-MM-DD 格式。
啟用小費	invoice.payment_requests.tipping_enabled	boolean	如果設定為 true，則為客戶提供支付小費的位置。
提醒	invoice.payment_requests.reminders	array of object
UID	invoice.payment_requests.reminders.uid	string	Square 指派的 ID。
相對排程天數	invoice.payment_requests.reminders.relative_scheduled_days	integer	付款請求之前（負數）或之後（正數）傳送提醒due_date的天數。
Message	invoice.payment_requests.reminders.message	string	訊息。
地位	invoice.payment_requests.reminders.status	string	目前狀態。
總數	invoice.payment_requests.computed_amount_money.amount	integer	金額。
貨幣	invoice.payment_requests.computed_amount_money.currency	string	貨幣。
總數	invoice.payment_requests.total_completed_amount_money.amount	integer	金額。
貨幣	invoice.payment_requests.total_completed_amount_money.currency	string	貨幣。
自動付款來源	invoice.payment_requests.automatic_payment_source	string	自動付款的付款方式。
發票號碼	invoice.invoice_number	string	用戶友好的發票號碼。該值在位置內是唯一的。如果在建立發票時未提供，Square 會指派一個值。
Title	invoice.title	string	標題。
Description	invoice.description	string	描述。
預定時間	invoice.scheduled_at	string	排程處理時的時間戳記，採用 RFC 3339 格式。
地位	invoice.status	string	此物件的目前驗證狀態。
Timezone	invoice.timezone	string	用來解譯行事曆日期的時區。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
創建於	invoice.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	invoice.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
客戶識別碼	invoice.primary_recipient.customer_id	string	與訂單相關聯的客戶識別碼。
名字	invoice.primary_recipient.given_name	string	收件人的給定（即名字）。
姓	invoice.primary_recipient.family_name	string	收件者的姓氏（即姓氏）。
電子郵件地址	invoice.primary_recipient.email_address	string	收件者的電子郵件地址。
電話號碼	invoice.primary_recipient.phone_number	string	收件者的電話號碼。
Card	invoice.accepted_payment_methods.card	boolean	指出是否接受信用卡或簽帳金融卡付款。
Square 禮品卡	invoice.accepted_payment_methods.square_gift_card	boolean	指出是否接受 Square 禮品卡付款。
銀行帳戶	invoice.accepted_payment_methods.bank_account	boolean	指出是否接受銀行轉帳付款。
自訂欄位	invoice.custom_fields	array of object
標籤	invoice.custom_fields.label	string	自訂欄位的標籤或標題。
價值觀	invoice.custom_fields.value	string	自訂欄位的文字。
放置	invoice.custom_fields.placement	string	發票上自訂欄位的位置。
送貨方式	invoice.delivery_method	string	Square 用來向顧客傳送發票、提醒和收據的配送方式。發票發布後，Square 會根據交付方式和付款請求設置處理發票，可以立即處理發票，也可以在scheduled_at日期處理發票（如果指定）。
銷售或服務日期	invoice.sale_or_service_date	string	銷售日期或提供服務的日期，以 YYYY-MM-DD 格式。此欄位可用來指定發票上顯示的過去或未來日期。

取得終端機結帳

作業識別碼：: TerminalGetCheckout

依checkout_id擷取終端機出庫要求。

參數

名稱	機碼	必要	類型	Description
結帳編號	checkout_id	True	string	結帳的識別碼。

傳回

名稱	路徑	類型	Description
ID	checkout.id	string	Square 發行的唯一識別碼。
總數	checkout.amount_money.amount	integer	金額。
貨幣	checkout.amount_money.currency	string	貨幣。
參考標識碼	checkout.reference_id	string	選用的使用者定義參照 ID。
備註	checkout.note	string	與客戶設定檔相關聯的自訂附註。
裝置標識碼	checkout.device_options.device_id	string	此 TerminalCheckout 之裝置的唯一識別碼。
允許給小費	checkout.device_options.tip_settings.allow_tipping	boolean	指出是否為此結帳啟用小費。預設為 False。
跳過收據畫面	checkout.device_options.skip_receipt_screen	boolean	指示裝置略過收據畫面。預設為 False。
地位	checkout.status	string	此物件的目前驗證狀態。
創建於	checkout.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	checkout.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
App ID	checkout.app_id	string	建立結帳的應用程式識別碼。
截止日期持續時間	checkout.deadline_duration	string	RFC 3339 持續時間，之後會自動取消結帳。 PENDING 的 TerminalCheckout 會自動取消，且取消原因為 TIMED_OUT。預設值：建立後 5 分鐘

取消付款

作業識別碼：: PaymentCancel

取消（作廢）付款。您可以使用此端點來取消狀態為「已核准」的付款。

參數

名稱	機碼	必要	類型	Description
付款標識碼	payment_id	True	string	付款的識別碼。

傳回

名稱	路徑	類型	Description
ID	payment.id	string	Square 發行的唯一識別碼。
創建於	payment.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	payment.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
總數	payment.amount_money.amount	integer	金額。
貨幣	payment.amount_money.currency	string	貨幣。
總數	payment.tip_money.amount	integer	金額。
貨幣	payment.tip_money.currency	string	貨幣。
地位	payment.status	string	此物件的目前驗證狀態。
延遲持續時間	payment.delay_duration	string	建立付款後，Square 自動將delay_action套用至付款的持續時間。此自動delay_action僅適用於在delay_duration時段之前未達到終止狀態（COMPLETED、CANCELED 或 FAILED）的付款。此欄位以 RFC 3339 格式指定為持續時間。
來源類型	payment.source_type	string	此付款的來源類型。目前值包括 CARD、BANK_ACCOUNT、WALLET、CASH 或 EXTERNAL。
地位	payment.card_details.status	string	目前狀態。
卡片品牌	payment.card_details.card.card_brand	string	卡片的品牌。
最後 4 名	payment.card_details.card.last_4	string	卡號的最後 4 位數字。
到期月	payment.card_details.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	payment.card_details.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	payment.card_details.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
卡片類型	payment.card_details.card.card_type	string	卡片的類型。
預付費類型	payment.card_details.card.prepaid_type	string	指示卡片是否預付。
垃圾箱	payment.card_details.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
報名方式	payment.card_details.entry_method	string	用於輸入卡詳細信息以進行付款的方法。該方法可以是 KEYED、SWIPED、EMV、ON_FILE 或 CONTACTLESS。
CVV 狀態	payment.card_details.cvv_status	string	從卡片驗證值（CVV）檢查傳回的狀態碼。代碼可以是CVV_ACCEPTED、CVV_REJECTED或CVV_NOT_CHECKED。
AVS 狀態	payment.card_details.avs_status	string	從地址驗證系統（AVS）檢查傳回的狀態碼。代碼可以是AVS_ACCEPTED、AVS_REJECTED或AVS_NOT_CHECKED。
驗證結果代碼	payment.card_details.auth_result_code	string	發卡機構傳回的狀態碼，描述付款的授權狀態。
報表說明	payment.card_details.statement_description	string	傳送至卡片網路的報表說明。
授權於	payment.card_details.card_payment_timeline.authorized_at	string	授權付款的時間戳記，採用 RFC 3339 格式。
無效時間	payment.card_details.card_payment_timeline.voided_at	string	付款作廢的時間戳記，採用 RFC 3339 格式。
位置標識碼	payment.location_id	string	位置的識別碼。
訂單編號	payment.order_id	string	訂單的識別碼。
創建於	payment.risk_evaluation.created_at	string	建立時的時間戳記，採用 RFC 3339 格式。
風險等級	payment.risk_evaluation.risk_level	string	與付款相關聯的風險等級。
備註	payment.note	string	與客戶設定檔相關聯的自訂附註。
客戶識別碼	payment.customer_id	string	此物件代表客戶的 ID。
總數	payment.total_money.amount	integer	金額。
貨幣	payment.total_money.currency	string	貨幣。
總數	payment.approved_money.amount	integer	金額。
貨幣	payment.approved_money.currency	string	貨幣。
延遲作	payment.delay_action	string	delay_duration過後要套用至付款的動作。
延遲至	payment.delayed_until	string	自動套用delay_action時的唯讀時間戳記，採用 RFC 3339 格式。
方形產品	payment.application_details.square_product	string	Square 產品，例如 Square 銷售點（POS）、Square 發票或 Square 虛擬終端機。
應用程式識別碼	payment.application_details.application_id	string	指派給應用程式的唯讀 Square ID。
版本令牌	payment.version_token	string	此不透明權杖可識別物件的特定版本。

取消發票

作業識別碼：: InvoiceCancel

取消發票。賣方無法收取已取消發票的付款。

參數

名稱	機碼	必要	類型	Description
發票識別碼	invoice_id	True	string	發票的識別碼。
版本	version		integer	版本。

傳回

名稱	路徑	類型	Description
ID	invoice.id	string	Square 發行的唯一識別碼。
版本	invoice.version	integer	此物件的目前版本。
位置標識碼	invoice.location_id	string	位置的識別碼。
訂單編號	invoice.order_id	string	訂單的識別碼。
付款請求	invoice.payment_requests	array of object
UID	invoice.payment_requests.uid	string	Square 產生的 ID。
請求類型	invoice.payment_requests.request_type	string	識別付款請求類型。此類型定義如何確定付款請求金額。
到期日	invoice.payment_requests.due_date	string	付款要求的到期日，以 YYYY-MM-DD 格式。
啟用小費	invoice.payment_requests.tipping_enabled	boolean	如果設定為 true，則為客戶提供支付小費的位置。
提醒	invoice.payment_requests.reminders	array of object
UID	invoice.payment_requests.reminders.uid	string	Square 指派的 ID。
相對排程天數	invoice.payment_requests.reminders.relative_scheduled_days	integer	付款請求之前（負數）或之後（正數）傳送提醒due_date的天數。
Message	invoice.payment_requests.reminders.message	string	訊息。
地位	invoice.payment_requests.reminders.status	string	目前狀態。
總數	invoice.payment_requests.computed_amount_money.amount	integer	金額。
貨幣	invoice.payment_requests.computed_amount_money.currency	string	貨幣。
總數	invoice.payment_requests.total_completed_amount_money.amount	integer	金額。
貨幣	invoice.payment_requests.total_completed_amount_money.currency	string	貨幣。
自動付款來源	invoice.payment_requests.automatic_payment_source	string	自動付款的付款方式。
發票號碼	invoice.invoice_number	string	用戶友好的發票號碼。該值在位置內是唯一的。如果在建立發票時未提供，Square 會指派一個值。
Title	invoice.title	string	標題。
Description	invoice.description	string	描述。
預定時間	invoice.scheduled_at	string	排程處理時的時間戳記，採用 RFC 3339 格式。
地位	invoice.status	string	此物件的目前驗證狀態。
Timezone	invoice.timezone	string	用來解譯行事曆日期的時區。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
創建於	invoice.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	invoice.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
客戶識別碼	invoice.primary_recipient.customer_id	string	與訂單相關聯的客戶識別碼。
名字	invoice.primary_recipient.given_name	string	收件人的給定（即名字）。
姓	invoice.primary_recipient.family_name	string	收件者的姓氏（即姓氏）。
電子郵件地址	invoice.primary_recipient.email_address	string	收件者的電子郵件地址。
電話號碼	invoice.primary_recipient.phone_number	string	收件者的電話號碼。
Card	invoice.accepted_payment_methods.card	boolean	指出是否接受信用卡或簽帳金融卡付款。
Square 禮品卡	invoice.accepted_payment_methods.square_gift_card	boolean	指出是否接受 Square 禮品卡付款。
銀行帳戶	invoice.accepted_payment_methods.bank_account	boolean	指出是否接受銀行轉帳付款。
自訂欄位	invoice.custom_fields	array of object
標籤	invoice.custom_fields.label	string	自訂欄位的標籤或標題。
價值觀	invoice.custom_fields.value	string	自訂欄位的文字。
放置	invoice.custom_fields.placement	string	發票上自訂欄位的位置。
送貨方式	invoice.delivery_method	string	Square 用來向顧客傳送發票、提醒和收據的配送方式。發票發布後，Square 會根據交付方式和付款請求設置處理發票，可以立即處理發票，也可以在scheduled_at日期處理發票（如果指定）。
銷售或服務日期	invoice.sale_or_service_date	string	銷售日期或提供服務的日期，以 YYYY-MM-DD 格式。此欄位可用來指定發票上顯示的過去或未來日期。

取消終端機結帳

作業識別碼：: TerminalCancelCheckout

如果要求的狀態允許，則取消終端機出庫要求。

參數

名稱	機碼	必要	類型	Description
結帳編號	checkout_id	True	string	結帳的識別碼。

傳回

名稱	路徑	類型	Description
ID	checkout.id	string	Square 發行的唯一識別碼。
總數	checkout.amount_money.amount	integer	金額。
貨幣	checkout.amount_money.currency	string	貨幣。
參考標識碼	checkout.reference_id	string	選用的使用者定義參照 ID。
裝置標識碼	checkout.device_options.device_id	string	此 TerminalCheckout 之裝置的唯一識別碼。
允許給小費	checkout.device_options.tip_settings.allow_tipping	boolean	指出是否為此結帳啟用小費。預設為 False。
跳過收據畫面	checkout.device_options.skip_receipt_screen	boolean	指示裝置略過收據畫面。預設為 False。
地位	checkout.status	string	此物件的目前驗證狀態。
取消原因	checkout.cancel_reason	string	取消交易的原因。
創建於	checkout.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	checkout.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
App ID	checkout.app_id	string	建立結帳的應用程式識別碼。
截止日期持續時間	checkout.deadline_duration	string	RFC 3339 持續時間，之後會自動取消結帳。 PENDING 的 TerminalCheckout 會自動取消，且取消原因為 TIMED_OUT。預設值：建立後 5 分鐘

取消航站樓退款

作業識別碼：: TerminalCancelRefund

如果要求狀態允許，則透過退款要求 ID 取消 Interac 終端機退款要求。

參數

名稱	機碼	必要	類型	Description
終端退款 ID	terminal_refund_id	True	string	終端機退款的識別碼。

傳回

名稱	路徑	類型	Description
ID	refund.id	string	Square 發行的唯一識別碼。
付款標識碼	refund.payment_id	string	付款的唯一 ID。
總數	refund.amount_money.amount	integer	金額。
貨幣	refund.amount_money.currency	string	貨幣。
原因	refund.reason	string	這個物件的原因。
裝置標識碼	refund.device_id	string	用於此終端機退款的裝置的唯一 ID。
截止日期持續時間	refund.deadline_duration	string	RFC 3339 持續時間，之後會自動取消結帳。 PENDING 的 TerminalCheckout 會自動取消，且取消原因為 TIMED_OUT。預設值：建立後 5 分鐘
地位	refund.status	string	此物件的目前驗證狀態。
取消原因	refund.cancel_reason	string	取消交易的原因。
創建於	refund.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	refund.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
App ID	refund.app_id	string	建立結帳的應用程式識別碼。
卡片品牌	refund.card.card_brand	string	卡片的品牌。
last_4	refund.card.last_4	string	卡號的最後 4 位數字。
到期月	refund.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	refund.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	refund.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
卡片類型	refund.card.card_type	string	卡片的類型。
垃圾箱	refund.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
訂單編號	refund.order_id	string	訂單的識別碼。
位置標識碼	refund.location_id	string	位置的識別碼。

取消訂閱

作業識別碼：: SubscriptionCancel

將canceled_date欄位設定為作用中計費期間的結尾。在此日期之後，狀態會從「作用中」變更為「已取消」。

參數

名稱	機碼	必要	類型	Description
訂用帳戶識別碼	subscription_id	True	string	訂用帳戶的識別碼。

傳回

名稱	路徑	類型	Description
ID	subscription.id	string	Square 發行的唯一識別碼。
位置標識碼	subscription.location_id	string	位置的識別碼。
方案標識碼	subscription.plan_id	string	相關聯訂閱方案的識別碼。
客戶識別碼	subscription.customer_id	string	此物件代表客戶的 ID。
卡片 ID	subscription.card_id	string	向訂閱收費的客戶卡識別碼。
開始日期	subscription.start_date	string	訂閱的開始日期，以 YYYY-MM-DD 格式。
取消日期	subscription.canceled_date	string	訂閱取消日期，以 YYYY-MM-DD 格式。
付款截止日期	subscription.paid_until_date	string	支付日期。
地位	subscription.status	string	此物件的目前驗證狀態。
創建於	subscription.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
版本	subscription.version	integer	此物件的目前版本。
Timezone	subscription.timezone	string	用來解譯行事曆日期的時區。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
名稱	subscription.source.name	string	名稱。

完成付款

作業識別碼：: PaymentComplete

完成（捕獲）付款。預設情況下，付款設定為在建立後立即完成。

參數

名稱	機碼	必要	類型	Description
付款標識碼	payment_id	True	string	付款的識別碼。

傳回

名稱	路徑	類型	Description
ID	payment.id	string	Square 發行的唯一識別碼。
創建於	payment.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	payment.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
總數	payment.amount_money.amount	integer	金額。
貨幣	payment.amount_money.currency	string	貨幣。
地位	payment.status	string	此物件的目前驗證狀態。
延遲持續時間	payment.delay_duration	string	建立付款後，Square 自動將delay_action套用至付款的持續時間。此自動delay_action僅適用於在delay_duration時段之前未達到終止狀態（COMPLETED、CANCELED 或 FAILED）的付款。此欄位以 RFC 3339 格式指定為持續時間。
來源類型	payment.source_type	string	此付款的來源類型。目前值包括 CARD、BANK_ACCOUNT、WALLET、CASH 或 EXTERNAL。
地位	payment.card_details.status	string	目前狀態。
卡片品牌	payment.card_details.card.card_brand	string	卡片的品牌。
最後 4 名	payment.card_details.card.last_4	string	卡號的最後 4 位數字。
到期月	payment.card_details.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	payment.card_details.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	payment.card_details.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
卡片類型	payment.card_details.card.card_type	string	卡片的類型。
預付費類型	payment.card_details.card.prepaid_type	string	指示卡片是否預付。
垃圾箱	payment.card_details.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
報名方式	payment.card_details.entry_method	string	用於輸入卡詳細信息以進行付款的方法。該方法可以是 KEYED、SWIPED、EMV、ON_FILE 或 CONTACTLESS。
CVV 狀態	payment.card_details.cvv_status	string	從卡片驗證值（CVV）檢查傳回的狀態碼。代碼可以是CVV_ACCEPTED、CVV_REJECTED或CVV_NOT_CHECKED。
AVS 狀態	payment.card_details.avs_status	string	從地址驗證系統（AVS）檢查傳回的狀態碼。代碼可以是AVS_ACCEPTED、AVS_REJECTED或AVS_NOT_CHECKED。
驗證結果代碼	payment.card_details.auth_result_code	string	發卡機構傳回的狀態碼，描述付款的授權狀態。
報表說明	payment.card_details.statement_description	string	傳送至卡片網路的報表說明。
授權於	payment.card_details.card_payment_timeline.authorized_at	string	授權付款的時間戳記，採用 RFC 3339 格式。
捕獲於	payment.card_details.card_payment_timeline.captured_at	string	擷取付款的時間戳記，採用 RFC 3339 格式。
位置標識碼	payment.location_id	string	位置的識別碼。
訂單編號	payment.order_id	string	訂單的識別碼。
手續費	payment.processing_fee	array of object
有效於	payment.processing_fee.effective_at	string	費用生效的時間戳記，採用 RFC 3339 格式。
類型	payment.processing_fee.type	string	指出類型。
總數	payment.processing_fee.amount_money.amount	integer	金額。
貨幣	payment.processing_fee.amount_money.currency	string	貨幣。
備註	payment.note	string	與客戶設定檔相關聯的自訂附註。
總數	payment.total_money.amount	integer	金額。
貨幣	payment.total_money.currency	string	貨幣。
總數	payment.approved_money.amount	integer	金額。
貨幣	payment.approved_money.currency	string	貨幣。
員工 ID	payment.employee_id	string	員工的 Square 產生的 ID。
收據號碼	payment.receipt_number	string	付款的收據號碼。如果取消付款，則會遺失此欄位。
收據網址	payment.receipt_url	string	付款收據的 URL。此欄位只會針對已完成的付款填入。
延遲作	payment.delay_action	string	delay_duration過後要套用至付款的動作。
延遲至	payment.delayed_until	string	自動套用delay_action時的唯讀時間戳記，採用 RFC 3339 格式。
團隊成員 ID	payment.team_member_id	string	團隊成員的 ID。
方形產品	payment.application_details.square_product	string	Square 產品，例如 Square 銷售點（POS）、Square 發票或 Square 虛擬終端機。
應用程式識別碼	payment.application_details.application_id	string	指派給應用程式的唯讀 Square ID。
版本令牌	payment.version_token	string	此不透明權杖可識別物件的特定版本。

將群組新增至客戶

作業識別碼：: CustomerAddGroup

將群組成員資格新增至客戶。客戶由customer_id值識別，客戶群組由group_id值識別。

參數

名稱	機碼	必要	類型	Description
客戶識別碼	customer_id	True	string	客戶的識別碼。
群組識別碼	group_id	True	string	群組的識別碼。

傳回

response: object

建立付款

作業識別碼：: PaymentCreate

使用提供的來源建立付款。您可以使用此端點向卡片（信用卡/簽帳金融卡或 Square 禮品卡）收費，或記錄賣家在 Square 之外收到的付款（來自買家的現金付款或外部實體代表賣家處理的付款）。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
總數	amount	integer	接受這筆付款的金額，不包括tip_money。
貨幣	currency	string	3 個字元的 ISO 4217 貨幣代碼。
來源 ID	source_id	string	此付款資金來源的 ID。這可以是 Square 付款表單產生的付款權杖（卡片隨機數），也可以是使用 Customers API 製作的存檔卡片。如果記錄賣家在 Square 之外收到的付款，請指定 CASH 或 EXTERNAL。
自動完成	autocomplete	boolean	如果設定為 true，則會在可能的情況下完成此付款。如果設定為 false，則此付款會保持在核准狀態，直到明確完成（擷取）或取消（作廢）。
客戶識別碼	customer_id	string	要連結的客戶 ID。
位置標識碼	location_id	string	位置識別碼。
參考標識碼	reference_id	string	選用的第二個 ID，用來將客戶設定檔與另一個系統中的實體建立關聯。
備註	note	string	與客戶設定檔相關聯的自訂附註。
總數	amount	integer	接受這筆付款的金額，不包括tip_money。
貨幣	currency	string	3 個字元的 ISO 4217 貨幣代碼。

傳回

名稱	路徑	類型	Description
ID	payment.id	string	Square 發行的唯一識別碼。
創建於	payment.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	payment.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
總數	payment.amount_money.amount	integer	金額。
貨幣	payment.amount_money.currency	string	貨幣。
總數	payment.app_fee_money.amount	integer	金額。
貨幣	payment.app_fee_money.currency	string	貨幣。
地位	payment.status	string	此物件的目前驗證狀態。
延遲持續時間	payment.delay_duration	string	建立付款後，Square 自動將delay_action套用至付款的持續時間。此自動delay_action僅適用於在delay_duration時段之前未達到終止狀態（COMPLETED、CANCELED 或 FAILED）的付款。此欄位以 RFC 3339 格式指定為持續時間。
來源類型	payment.source_type	string	此付款的來源類型。目前值包括 CARD、BANK_ACCOUNT、WALLET、CASH 或 EXTERNAL。
地位	payment.card_details.status	string	目前狀態。
卡片品牌	payment.card_details.card.card_brand	string	卡片的品牌。
最後 4 名	payment.card_details.card.last_4	string	卡號的最後 4 位數字。
到期月	payment.card_details.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	payment.card_details.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	payment.card_details.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
卡片類型	payment.card_details.card.card_type	string	卡片的類型。
預付費類型	payment.card_details.card.prepaid_type	string	指示卡片是否預付。
垃圾箱	payment.card_details.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
報名方式	payment.card_details.entry_method	string	用於輸入卡詳細信息以進行付款的方法。該方法可以是 KEYED、SWIPED、EMV、ON_FILE 或 CONTACTLESS。
CVV 狀態	payment.card_details.cvv_status	string	從卡片驗證值（CVV）檢查傳回的狀態碼。代碼可以是CVV_ACCEPTED、CVV_REJECTED或CVV_NOT_CHECKED。
AVS 狀態	payment.card_details.avs_status	string	從地址驗證系統（AVS）檢查傳回的狀態碼。代碼可以是AVS_ACCEPTED、AVS_REJECTED或AVS_NOT_CHECKED。
驗證結果代碼	payment.card_details.auth_result_code	string	發卡機構傳回的狀態碼，描述付款的授權狀態。
報表說明	payment.card_details.statement_description	string	傳送至卡片網路的報表說明。
授權於	payment.card_details.card_payment_timeline.authorized_at	string	授權付款的時間戳記，採用 RFC 3339 格式。
捕獲於	payment.card_details.card_payment_timeline.captured_at	string	擷取付款的時間戳記，採用 RFC 3339 格式。
位置標識碼	payment.location_id	string	位置的識別碼。
訂單編號	payment.order_id	string	訂單的識別碼。
參考標識碼	payment.reference_id	string	選用的使用者定義參照 ID。
創建於	payment.risk_evaluation.created_at	string	建立時的時間戳記，採用 RFC 3339 格式。
風險等級	payment.risk_evaluation.risk_level	string	與付款相關聯的風險等級。
備註	payment.note	string	與客戶設定檔相關聯的自訂附註。
客戶識別碼	payment.customer_id	string	此物件代表客戶的 ID。
總數	payment.total_money.amount	integer	金額。
貨幣	payment.total_money.currency	string	貨幣。
總數	payment.approved_money.amount	integer	金額。
貨幣	payment.approved_money.currency	string	貨幣。
收據號碼	payment.receipt_number	string	付款的收據號碼。如果取消付款，則會遺失此欄位。
收據網址	payment.receipt_url	string	付款收據的 URL。此欄位只會針對已完成的付款填入。
延遲作	payment.delay_action	string	delay_duration過後要套用至付款的動作。
延遲至	payment.delayed_until	string	自動套用delay_action時的唯讀時間戳記，採用 RFC 3339 格式。
方形產品	payment.application_details.square_product	string	Square 產品，例如 Square 銷售點（POS）、Square 發票或 Square 虛擬終端機。
應用程式識別碼	payment.application_details.application_id	string	指派給應用程式的唯讀 Square ID。
版本令牌	payment.version_token	string	此不透明權杖可識別物件的特定版本。

建立卡片

作業識別碼：: CardCreate

將存檔的卡片新增至現有商家。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	冪等鍵。
來源 ID	source_id	string	來源的識別碼。
地址行 1	address_line_1	string	地址的第一行。以address_line開頭的欄位提供地址最具體的詳細信息，例如街道號碼、街道名稱和建築物名稱。
地址行 2	address_line_2	string	地址的第二行（如果有的話）。
地區	locality	string	地址所在的城市或城鎮。
行政區一級	administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	postal_code	string	地址的郵遞區號。
國家	country	string	地址的國家/地區，採用 ISO 3166-1-alpha-2 格式。
持卡人姓名	cardholder_name	string	持卡人的姓名。
客戶識別碼	customer_id	string	此物件代表客戶的 ID。
參考標識碼	reference_id	string	選用的使用者定義參照 ID。

傳回

名稱	路徑	類型	Description
ID	card.id	string	Square 發行的唯一識別碼。
地址行 1	card.billing_address.address_line_1	string	地址的第一行。以address_line開頭的欄位提供地址最具體的詳細信息，例如街道號碼、街道名稱和建築物名稱。
地址行 2	card.billing_address.address_line_2	string	地址的第二行（如果有的話）。
地區	card.billing_address.locality	string	地址所在的城市或城鎮。
行政區一級	card.billing_address.administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	card.billing_address.postal_code	string	地址的郵遞區號。
國家	card.billing_address.country	string	地址的國家/地區，採用 ISO 3166-1-alpha-2 格式。
指紋	card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
垃圾箱	card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
卡片品牌	card.card_brand	string	卡片的品牌。
卡片類型	card.card_type	string	卡片的類型。
持卡人姓名	card.cardholder_name	string	持卡人的姓名。
客戶識別碼	card.customer_id	string	此物件代表客戶的 ID。
已啟用	card.enabled	boolean	是否啟用。
到期月	card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	card.exp_year	integer	卡片到期日期的四位數年份。
最後 4 名	card.last_4	string	卡號的最後 4 位數字。
預付費類型	card.prepaid_type	string	指示卡片是否預付。
參考標識碼	card.reference_id	string	選用的使用者定義參照 ID。
版本	card.version	integer	此物件的目前版本。

建立客戶

作業識別碼：: CustomerCreate

為企業建立新客戶。

參數

名稱	機碼	類型	Description
名字	given_name	string	與客戶設定檔相關聯的給定名稱（即名字）。
姓	family_name	string	與客戶設定檔相關聯的姓氏（亦即姓氏）。
電子郵件地址	email_address	string	與客戶設定檔相關聯的電子郵件地址。
公司名稱	company_name	string	與客戶設定檔相關聯的企業名稱。
暱稱	nickname	string	客戶設定檔的暱稱。
地址行 1	address_line_1	string	地址的第一行。
地址行 2	address_line_2	string	地址的第二行（如果有的話）。
地區	locality	string	地址所在的城市或城鎮。
行政區一級	administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	postal_code	string	地址的郵遞區號。
國家	country	string	ISO 3166 Alpha-2 國家代碼。
電話號碼	phone_number	string	與客戶設定檔相關聯的 11 位電話號碼。
參考標識碼	reference_id	string	選用的第二個 ID，用來將客戶設定檔與另一個系統中的實體建立關聯。
備註	note	string	與客戶設定檔相關聯的自訂附註。
生日	birthday	string	與客戶設定檔相關聯的生日，採用 RFC 3339 格式。年份是可選的。不允許使用時區和時間。例如，0000-09-21T00：00：00-00：00 代表 9 月 21 日的生日，而 1998-09-21T00：00：00-00：00 代表 1998 年 9 月 21 日的生日。您也可以以 YYYY-MM-DD 格式指定此值。

傳回

名稱	路徑	類型	Description
ID	customer.id	string	Square 發行的唯一識別碼。
創建於	customer.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	customer.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
名字	customer.given_name	string	與客戶設定檔相關聯的給定（即名字）名稱。
姓	customer.family_name	string	與客戶設定檔相關聯的家族（即姓氏）名稱。
電子郵件地址	customer.email_address	string	與客戶設定檔相關聯的電子郵件地址。
公司名稱	customer.company_name	string	與客戶設定檔相關聯的企業名稱。
暱稱	customer.nickname	string	客戶設定檔的暱稱。
地址行 1	customer.address.address_line_1	string	地址的第一行。以address_line開頭的欄位提供地址最具體的詳細信息，例如街道號碼、街道名稱和建築物名稱。
地址行 2	customer.address.address_line_2	string	地址的第二行（如果有的話）。
地區	customer.address.locality	string	地址所在的城市或城鎮。
行政區一級	customer.address.administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	customer.address.postal_code	string	地址的郵遞區號。
國家	customer.address.country	string	地址的國家/地區，採用 ISO 3166-1-alpha-2 格式。
電話號碼	customer.phone_number	string	與客戶設定檔相關聯的 11 位電話號碼。
參考標識碼	customer.reference_id	string	選用的使用者定義參照 ID。
備註	customer.note	string	與客戶設定檔相關聯的自訂附註。
生日	customer.birthday	string	與客戶設定檔相關聯的生日，採用 RFC 3339 格式。年份是可選的。不允許使用時區和時間。例如，0000-09-21T00：00：00-00：00 代表 9 月 21 日的生日，而 1998-09-21T00：00：00-00：00 代表 1998 年 9 月 21 日的生日。
電子郵件取消訂閱	customer.preferences.email_unsubscribed	boolean	指出客戶是否已取消訂閱行銷活動電子郵件。值為 true 表示客戶選擇退出目前 Square 賣家或所有 Square 賣家的電子郵件行銷。
創作來源	customer.creation_source	string	建立來源代表用來建立客戶設定檔的方法。
版本	customer.version	integer	此物件的目前版本。

建立客戶群組

作業識別碼：: CustomGroupCreate

為企業建立新的客戶群組。

參數

名稱	機碼	必要	類型	Description
名稱	name		string	物件的名稱。

傳回

名稱	路徑	類型	Description
ID	group.id	string	Square 發行的唯一識別碼。
名稱	group.name	string	物件的名稱。
創建於	group.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	group.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。

建立爭議辨識項文字

作業識別碼：: DisputeCreateEvidenceText

上傳文字以用作爭議挑戰的證據。

參數

名稱	機碼	必要	類型	Description
爭議 ID	dispute_id	True	string	爭議的標識符。
辨識項類型	evidence_type		string	您要上傳的證據類型。
證據文本	evidence_text		string	證據字串。
冪等金鑰	idempotency_key		string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。

傳回

名稱	路徑	類型	Description
ID	evidence.id	string	Square 發行的唯一識別碼。
爭議 ID	evidence.dispute_id	string	與證據相關聯的爭議 ID。
證據文本	evidence.evidence_text	string	原始文本。
辨識項類型	evidence.evidence_type	string	類型 pf 證據。
上傳於	evidence.uploaded_at	string	下一個動作到期的時間，採用 RFC 3339 格式。

建立發票

作業識別碼：: InvoiceCreate

為使用訂單API建立的訂單建立草稿發票。草稿發票仍保留在您的帳戶中，不會採取任何行動。您必須先發布發票，然後 Square 才能處理發票（將其發送到客戶的電子郵件地址或從客戶存檔的卡中扣款）。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
位置標識碼	location_id	string	位置的識別碼。
訂單編號	order_id	string	訂單的識別碼。
預定時間	scheduled_at	string	排程處理時的時間戳記，採用 RFC 3339 格式。
客戶識別碼	customer_id	string	與訂單相關聯的客戶識別碼。
送貨方式	delivery_method	string	Square 用來向顧客傳送發票、提醒和收據的配送方式。發票發布後，Square 會根據交付方式和付款請求設置處理發票，可以立即處理發票，也可以在scheduled_at日期處理發票（如果指定）。
請求類型	request_type	string	識別付款請求類型。此類型定義如何確定付款請求金額。
到期日	due_date	string	付款要求的到期日，以 YYYY-MM-DD 格式。
啟用小費	tipping_enabled	boolean	如果設定為 true，則為客戶提供支付小費的位置。
自動付款來源	automatic_payment_source	string	自動付款的付款方式。
Message	message	string	訊息。
相對排程天數	relative_scheduled_days	integer	付款請求之前（負數）或之後（正數）傳送提醒due_date的天數。
發票號碼	invoice_number	string	用戶友好的發票號碼。該值在位置內是唯一的。如果在建立發票時未提供，Square 會指派一個值。
Title	title	string	標題。
Description	description	string	描述。
Card	card	boolean	指出是否接受信用卡或簽帳金融卡付款。
Square 禮品卡	square_gift_card	boolean	指出是否接受 Square 禮品卡付款。
銀行帳戶	bank_account	boolean	指出是否接受銀行轉帳付款。
標籤	label	string	自訂欄位的標籤或標題。
價值觀	value	string	自訂欄位的文字。
放置	placement	string	發票上自訂欄位的位置。
銷售或服務日期	sale_or_service_date	string	銷售日期或提供服務的日期，以 YYYY-MM-DD 格式。此欄位可用來指定發票上顯示的過去或未來日期。

傳回

名稱	路徑	類型	Description
ID	invoice.id	string	Square 發行的唯一識別碼。
版本	invoice.version	integer	此物件的目前版本。
位置標識碼	invoice.location_id	string	位置的識別碼。
訂單編號	invoice.order_id	string	訂單的識別碼。
付款請求	invoice.payment_requests	array of object
UID	invoice.payment_requests.uid	string	Square 產生的 ID。
請求類型	invoice.payment_requests.request_type	string	識別付款請求類型。此類型定義如何確定付款請求金額。
到期日	invoice.payment_requests.due_date	string	付款要求的到期日，以 YYYY-MM-DD 格式。
啟用小費	invoice.payment_requests.tipping_enabled	boolean	如果設定為 true，則為客戶提供支付小費的位置。
提醒	invoice.payment_requests.reminders	array of object
UID	invoice.payment_requests.reminders.uid	string	Square 指派的 ID。
相對排程天數	invoice.payment_requests.reminders.relative_scheduled_days	integer	付款請求之前（負數）或之後（正數）傳送提醒due_date的天數。
Message	invoice.payment_requests.reminders.message	string	訊息。
地位	invoice.payment_requests.reminders.status	string	目前狀態。
總數	invoice.payment_requests.computed_amount_money.amount	integer	金額。
貨幣	invoice.payment_requests.computed_amount_money.currency	string	貨幣。
總數	invoice.payment_requests.total_completed_amount_money.amount	integer	金額。
貨幣	invoice.payment_requests.total_completed_amount_money.currency	string	貨幣。
自動付款來源	invoice.payment_requests.automatic_payment_source	string	自動付款的付款方式。
發票號碼	invoice.invoice_number	string	用戶友好的發票號碼。該值在位置內是唯一的。如果在建立發票時未提供，Square 會指派一個值。
Title	invoice.title	string	標題。
Description	invoice.description	string	描述。
預定時間	invoice.scheduled_at	string	排程處理時的時間戳記，採用 RFC 3339 格式。
地位	invoice.status	string	此物件的目前驗證狀態。
Timezone	invoice.timezone	string	用來解譯行事曆日期的時區。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
創建於	invoice.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	invoice.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
客戶識別碼	invoice.primary_recipient.customer_id	string	與訂單相關聯的客戶識別碼。
名字	invoice.primary_recipient.given_name	string	收件人的給定（即名字）。
姓	invoice.primary_recipient.family_name	string	收件者的姓氏（即姓氏）。
電子郵件地址	invoice.primary_recipient.email_address	string	收件者的電子郵件地址。
電話號碼	invoice.primary_recipient.phone_number	string	收件者的電話號碼。
Card	invoice.accepted_payment_methods.card	boolean	指出是否接受信用卡或簽帳金融卡付款。
Square 禮品卡	invoice.accepted_payment_methods.square_gift_card	boolean	指出是否接受 Square 禮品卡付款。
銀行帳戶	invoice.accepted_payment_methods.bank_account	boolean	指出是否接受銀行轉帳付款。
自訂欄位	invoice.custom_fields	array of object
標籤	invoice.custom_fields.label	string	自訂欄位的標籤或標題。
價值觀	invoice.custom_fields.value	string	自訂欄位的文字。
放置	invoice.custom_fields.placement	string	發票上自訂欄位的位置。
送貨方式	invoice.delivery_method	string	Square 用來向顧客傳送發票、提醒和收據的配送方式。發票發布後，Square 會根據交付方式和付款請求設置處理發票，可以立即處理發票，也可以在scheduled_at日期處理發票（如果指定）。
銷售或服務日期	invoice.sale_or_service_date	string	銷售日期或提供服務的日期，以 YYYY-MM-DD 格式。此欄位可用來指定發票上顯示的過去或未來日期。

建立終端機出庫

作業識別碼：: TerminalCreateCheckout

建立終端機結帳請求並將其傳送到指定的裝置，以收取請求金額的付款。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
總數	amount	integer	金額。
貨幣	currency	string	貨幣。
參考標識碼	reference_id	string	選用的使用者定義參照 ID。
裝置標識碼	device_id	string	此 TerminalCheckout 之裝置的唯一識別碼。
備註	note	string	與客戶設定檔相關聯的自訂附註。

傳回

名稱	路徑	類型	Description
ID	checkout.id	string	Square 發行的唯一識別碼。
總數	checkout.amount_money.amount	integer	金額。
貨幣	checkout.amount_money.currency	string	貨幣。
參考標識碼	checkout.reference_id	string	選用的使用者定義參照 ID。
備註	checkout.note	string	與客戶設定檔相關聯的自訂附註。
裝置標識碼	checkout.device_options.device_id	string	此 TerminalCheckout 之裝置的唯一識別碼。
允許給小費	checkout.device_options.tip_settings.allow_tipping	boolean	指出是否為此結帳啟用小費。預設為 False。
跳過收據畫面	checkout.device_options.skip_receipt_screen	boolean	指示裝置略過收據畫面。預設為 False。
地位	checkout.status	string	此物件的目前驗證狀態。
創建於	checkout.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	checkout.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
App ID	checkout.app_id	string	建立結帳的應用程式識別碼。
截止日期持續時間	checkout.deadline_duration	string	RFC 3339 持續時間，之後會自動取消結帳。 PENDING 的 TerminalCheckout 會自動取消，且取消原因為 TIMED_OUT。預設值：建立後 5 分鐘
付款類型	checkout.payment_type	string	終端機應嘗試擷取的付款類型。預設為CARD_PRESENT。

建立終端退款

作業識別碼：: TerminalCreateRefund

建立退款請求，以退還在 Square Terminal 上完成的 Interac 付款。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
總數	amount	integer	金額。
貨幣	currency	string	貨幣。
裝置標識碼	device_id	string	用於此終端機退款的裝置的唯一 ID。
原因	reason	string	這個物件的原因。
付款標識碼	payment_id	string	付款的唯一 ID。

傳回

名稱	路徑	類型	Description
ID	refund.id	string	Square 發行的唯一識別碼。
付款標識碼	refund.payment_id	string	付款的唯一 ID。
總數	refund.amount_money.amount	integer	金額。
貨幣	refund.amount_money.currency	string	貨幣。
原因	refund.reason	string	這個物件的原因。
裝置標識碼	refund.device_id	string	用於此終端機退款的裝置的唯一 ID。
截止日期持續時間	refund.deadline_duration	string	RFC 3339 持續時間，之後會自動取消結帳。 PENDING 的 TerminalCheckout 會自動取消，且取消原因為 TIMED_OUT。預設值：建立後 5 分鐘
地位	refund.status	string	此物件的目前驗證狀態。
創建於	refund.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	refund.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
App ID	refund.app_id	string	建立結帳的應用程式識別碼。
卡片品牌	refund.card.card_brand	string	卡片的品牌。
last_4	refund.card.last_4	string	卡號的最後 4 位數字。
到期月	refund.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	refund.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	refund.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
卡片類型	refund.card.card_type	string	卡片的類型。
垃圾箱	refund.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
訂單編號	refund.order_id	string	訂單的識別碼。
位置標識碼	refund.location_id	string	位置的識別碼。

建立訂單

作業識別碼：: OrderCreate

建立新訂單，其中可以包含要購買的產品和要套用至購買的設定的相關資訊。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
參考標識碼	reference_id	string	選用的使用者定義參照 ID。
位置標識碼	location_id	string	位置的識別碼。
名稱	name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
數量	quantity	string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
總數	amount	integer	金額。
貨幣	currency	string	貨幣。
目錄物件識別碼	catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
目錄物件識別碼	catalog_object_id	string	目錄物件 ID。
折扣 UID	discount_uid	string	套用折扣所代表的折扣 uid。
UID	uid	string	Square 產生的 ID。
名稱	name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
百分比	percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
Scope	scope	string	指出目前的層級。
UID	uid	string	Square 產生的 ID。
名稱	name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
百分比	percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
Scope	scope	string	指出目前的層級。
目錄物件識別碼	catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
總數	amount	integer	金額。
貨幣	currency	string	貨幣。

傳回

名稱	路徑	類型	Description
ID	order.id	string	Square 發行的唯一識別碼。
位置標識碼	order.location_id	string	位置的識別碼。
明細項目	order.line_items	array of object
UID	order.line_items.uid	string	Square 產生的 ID。
名稱	order.line_items.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
數量	order.line_items.quantity	string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
適用稅項	order.line_items.applied_taxes	array of object
UID	order.line_items.applied_taxes.uid	string	Square 指派的 ID。
稅務 UID	order.line_items.applied_taxes.tax_uid	string	此套用稅金所代表之稅金的 UID。
總數	order.line_items.applied_taxes.applied_money.amount	integer	金額。
貨幣	order.line_items.applied_taxes.applied_money.currency	string	貨幣。
適用折扣	order.line_items.applied_discounts	array of object
UID	order.line_items.applied_discounts.uid	string	Square 指派的 ID。
折扣 UID	order.line_items.applied_discounts.discount_uid	string	套用折扣所代表的折扣 uid。
總數	order.line_items.applied_discounts.applied_money.amount	integer	金額。
貨幣	order.line_items.applied_discounts.applied_money.currency	string	貨幣。
總數	order.line_items.base_price_money.amount	integer	金額。
貨幣	order.line_items.base_price_money.currency	string	貨幣。
總數	order.line_items.gross_sales_money.amount	integer	金額。
貨幣	order.line_items.gross_sales_money.currency	string	貨幣。
總數	order.line_items.total_tax_money.amount	integer	金額。
貨幣	order.line_items.total_tax_money.currency	string	貨幣。
總數	order.line_items.total_discount_money.amount	integer	金額。
貨幣	order.line_items.total_discount_money.currency	string	貨幣。
總數	order.line_items.total_money.amount	integer	金額。
貨幣	order.line_items.total_money.currency	string	貨幣。
總數	order.line_items.variation_total_price_money.amount	integer	金額。
貨幣	order.line_items.variation_total_price_money.currency	string	貨幣。
目錄物件識別碼	order.line_items.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
變化名稱	order.line_items.variation_name	string	套用至此明細項目的變數名稱。
修飾詞	order.line_items.modifiers	array of object
UID	order.line_items.modifiers.uid	string	Square 指派的 ID。
目錄物件識別碼	order.line_items.modifiers.catalog_object_id	string	目錄物件 ID。
名稱	order.line_items.modifiers.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
總數	order.line_items.modifiers.base_price_money.amount	integer	金額。
貨幣	order.line_items.modifiers.base_price_money.currency	string	貨幣。
總數	order.line_items.modifiers.total_price_money.amount	integer	金額。
貨幣	order.line_items.modifiers.total_price_money.currency	string	貨幣。
稅款	order.taxes	array of object
UID	order.taxes.uid	string	Square 產生的 ID。
名稱	order.taxes.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
類型	order.taxes.type	string	指出類型。
百分比	order.taxes.percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
總數	order.taxes.applied_money.amount	integer	金額。
貨幣	order.taxes.applied_money.currency	string	貨幣。
Scope	order.taxes.scope	string	指出目前的層級。
折扣	order.discounts	array of object
UID	order.discounts.uid	string	Square 產生的 ID。
目錄物件識別碼	order.discounts.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
名稱	order.discounts.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
類型	order.discounts.type	string	指出類型。
百分比	order.discounts.percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
總數	order.discounts.applied_money.amount	integer	金額。
貨幣	order.discounts.applied_money.currency	string	貨幣。
Scope	order.discounts.scope	string	指出目前的層級。
總數	order.discounts.amount_money.amount	integer	金額。
貨幣	order.discounts.amount_money.currency	string	貨幣。
創建於	order.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	order.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
State	order.state	string	目前的狀態。
版本	order.version	integer	此物件的目前版本。
參考標識碼	order.reference_id	string	選用的使用者定義參照 ID。
總數	order.total_money.amount	integer	金額。
貨幣	order.total_money.currency	string	貨幣。
總數	order.total_tax_money.amount	integer	金額。
貨幣	order.total_tax_money.currency	string	貨幣。
總數	order.total_discount_money.amount	integer	金額。
貨幣	order.total_discount_money.currency	string	貨幣。
總數	order.total_tip_money.amount	integer	金額。
貨幣	order.total_tip_money.currency	string	貨幣。
總數	order.total_service_charge_money.amount	integer	金額。
貨幣	order.total_service_charge_money.currency	string	貨幣。
總數	order.net_amounts.total_money.amount	integer	金額。
貨幣	order.net_amounts.total_money.currency	string	貨幣。
總數	order.net_amounts.tax_money.amount	integer	金額。
貨幣	order.net_amounts.tax_money.currency	string	貨幣。
總數	order.net_amounts.discount_money.amount	integer	金額。
貨幣	order.net_amounts.discount_money.currency	string	貨幣。
總數	order.net_amounts.tip_money.amount	integer	金額。
貨幣	order.net_amounts.tip_money.currency	string	貨幣。
總數	order.net_amounts.service_charge_money.amount	integer	金額。
貨幣	order.net_amounts.service_charge_money.currency	string	貨幣。
名稱	order.source.name	string	名稱。

建立訂用帳戶

作業識別碼：: SubscriptionCreate

為客戶建立訂閱方案的訂閱。如果您在請求中提供了存檔的卡，Square 會向該卡收取訂閱費用。否則，Square 會向客戶的電子郵件地址開具帳單。訂閱會立即啟動，除非要求包含選用start_date。每個單獨的訂閱都與特定位置相關聯。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
位置標識碼	location_id	string	位置識別碼。
方案標識碼	plan_id	string	使用目錄API建立的訂閱計畫ID。
客戶識別碼	customer_id	string	要連結的客戶 ID。
卡片 ID	card_id	string	要扣款的客戶卡的 ID。
開始日期	start_date	string	訂閱的開始日期，以 YYYY-MM-DD 格式。
稅率	tax_percentage	string	對訂閱收費時要新增的稅金。
總數	amount	integer	接受這筆付款的金額，不包括tip_money。
貨幣	currency	string	3 個字元的 ISO 4217 貨幣代碼。
Timezone	timezone	string	用於訂閱日期計算的時區。
名稱	name	string	物件的名稱。

傳回

名稱	路徑	類型	Description
ID	subscription.id	string	Square 發行的唯一識別碼。
位置標識碼	subscription.location_id	string	位置的識別碼。
方案標識碼	subscription.plan_id	string	相關聯訂閱方案的識別碼。
客戶識別碼	subscription.customer_id	string	此物件代表客戶的 ID。
開始日期	subscription.start_date	string	訂閱的開始日期，以 YYYY-MM-DD 格式。
地位	subscription.status	string	此物件的目前驗證狀態。
稅率	subscription.tax_percentage	string	對訂閱計費時套用的稅額。
總數	subscription.price_override_money.amount	integer	金額。
貨幣	subscription.price_override_money.currency	string	貨幣。
版本	subscription.version	integer	此物件的目前版本。
創建於	subscription.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
卡片 ID	subscription.card_id	string	向訂閱收費的客戶卡識別碼。
Timezone	subscription.timezone	string	用來解譯行事曆日期的時區。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
名稱	subscription.source.name	string	名稱。

從客戶中移除群組

作業識別碼：: CustomerRemoveGroup

從客戶移除群組成員資格。客戶由customer_id值識別，客戶群組由group_id值識別。

參數

名稱	機碼	必要	類型	Description
客戶識別碼	customer_id	True	string	客戶的識別碼。
群組識別碼	group_id	True	string	群組的識別碼。

傳回

response: object

批次刪除目錄物件

作業識別碼：: CatalogBatchDelete

根據提供的目標識別碼清單刪除一組 CatalogItems，並在回應中傳回一組成功刪除的識別碼。

參數

名稱	機碼	必要	類型	Description
物件識別碼	object_ids		array of string

傳回

名稱	路徑	類型	Description
已刪除的物件 ID	deleted_object_ids	array of string
刪除時間	deleted_at	string	此刪除的資料庫時間戳記，採用 RFC 3339 格式

批次擷取庫存盤點

作業識別碼：: InventoryBatchRetrieveCounts

傳回所要求位置所提供 CatalogObjects 的目前計數。

參數

名稱	機碼	類型	Description
目錄物件識別碼	catalog_object_ids	array of string
位置 ID	location_ids	array of string
更新時間	updated_after	string	篩選器，在 RFC 3339 時間戳記中指定的指定時間之後傳回結果及其calculated_at值。

傳回

名稱	路徑	類型	Description
計數	counts	array of object
目錄物件識別碼	counts.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
目錄物件類型	counts.catalog_object_type	string	所追蹤的 CatalogObject 類型。
State	counts.state	string	目前的狀態。
位置標識碼	counts.location_id	string	位置的識別碼。
數量	counts.quantity	string	受估計計數影響的項目數，以十進位字串形式。最多可支援小數點後 5 位數字。
計算時間	counts.calculated_at	string	RFC 3339 格式的時間戳記，指出何時收到影響預估計數的最新實體計數或調整。

批次擷取庫存變更

作業識別碼：: InventoryBatchRetrieveChanges

根據提供的篩選條件傳回歷史實體計數和調整。

參數

名稱	機碼	類型	Description
目錄物件識別碼	catalog_object_ids	array of string
位置 ID	location_ids	array of string
型別	types	array of string
States	states	array of string
更新時間	updated_after	string	篩選器，在 RFC 3339 時間戳記中指定的指定時間之後傳回結果及其calculated_at值。
更新日期	updated_before	string	篩選器可傳回結果，其created_at值或calculated_at值嚴格在 RFC 3339 時間戳記中指定的指定時間之前。

傳回

名稱	路徑	類型	Description
Changes	changes	array of object
類型	changes.type	string	此物件的類型。
ID	changes.physical_count.id	string	物件的識別碼
參考標識碼	changes.physical_count.reference_id	string	選用的使用者定義參照 ID，可將此卡與外部系統中的另一個實體相關聯。
目錄物件識別碼	changes.physical_count.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
目錄物件類型	changes.physical_count.catalog_object_type	string	所追蹤的 CatalogObject 類型。
State	changes.physical_count.state	string	相關品項數量的目前庫存狀態。
位置標識碼	changes.physical_count.location_id	string	接收此投標部分的收件人（商家除外）的位置 ID。
數量	changes.physical_count.quantity	string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
Product	changes.physical_count.source.product	string	應用程式的產品類型。
應用程式識別碼	changes.physical_count.source.application_id	string	分配給應用程序的 Square ID。
名稱	changes.physical_count.source.name	string	項目的名稱。
員工 ID	changes.physical_count.employee_id	string	負責實際盤點的員工的 Square 產生的 ID。
發生於	changes.physical_count.occurred_at	string	用戶端產生的 RFC 3339 格式時間戳記，指出檢查實體計數的時間。對於實體計數更新，occurred_at時間戳記不能早於 24 小時，也不能相對於請求時間的未來。
創建於	changes.physical_count.created_at	string	用戶端產生的 RFC 3339 格式時間戳記，指出實體計數的建立時間。

批次擷取目錄物件

作業識別碼：: CatalogBatchRetrieve

根據提供的 ID 傳回一組物件。集合中傳回的每個 CatalogItem 都包含其所有子資訊，包括：其所有 CatalogItemVariation 物件、其 CatalogModifierList 物件的參考，以及套用至它的任何 CatalogTax 物件的識別碼。

參數

名稱	機碼	類型	Description
物件識別碼	object_ids	array of string
目錄版本	catalog_version	integer	要包含在回應中的目錄物件的特定版本。這可讓您擷取物件的歷史版本。指定的版本值會與 CatalogObjects 的版本屬性相符。
包含相關物件	include_related_objects	boolean	如果為 true，回應將包含與要求物件相關的其他物件，如下所示：如果回應的 objects 欄位包含 CatalogItem，則會在回應的 related_objects 欄位中傳回其相關聯的 CatalogCategory 物件、CatalogTax 物件、CatalogImage 物件和 CatalogModifierLists。如果回應的 objects 欄位包含 CatalogItemVariation，則會在回應的 related_objects 欄位中傳回其父 CatalogItem。

傳回

名稱	路徑	類型	Description
物件	objects	array of object
類型	objects.type	string	此物件的類型。
ID	objects.id	string	Square 發行的唯一識別碼。
更新於	objects.updated_at	string	RFC 3339 格式的上次修改時間戳記
版本	objects.version	integer	物件的目前版本。
已刪除	objects.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
出現在所有地點	objects.present_at_all_locations	boolean	如果為 true，則此物件存在於所有位置（包括未來的位置），除非在 absent_at_location_ids 欄位中指定。如果為 false，則此物件不會出現在任何位置（包括未來的位置），除非在 present_at_location_ids 欄位中指定。如果未指定，則預設為 true。
名稱	objects.item_data.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
Description	objects.item_data.title	string	項目的描述。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
類別標識碼	objects.item_data.category_id	string	項目類別的識別碼（如果有的話）。
稅務識別碼	objects.item_data.tax_ids	array of string
Variations	objects.item_data.variations	array of object
類型	objects.item_data.variations.type	string	此物件的類型。每個物件類型在下面的對應 *_data 欄位中都有以結構化格式表示的預期屬性。
ID	objects.item_data.variations.id	string	參考此物件的識別碼。
更新於	objects.item_data.variations.updated_at	string	RFC 3339 格式的上次修改時間戳記
版本	objects.item_data.variations.version	integer	物件的版本。更新物件時，提供的版本必須與資料庫中的版本相符，否則寫入將因衝突而被拒絕。
已刪除	objects.item_data.variations.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
出現在所有地點	objects.item_data.variations.present_at_all_locations	boolean	物件存在的位置清單，即使present_at_all_locations為 false。這可能包括已停用的位置。
項目 ID	objects.item_data.variations.item_variation_data.item_id	string	具有此項目變化的物件 ID。
名稱	objects.item_data.variations.item_variation_data.name	string	此項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
序數	objects.item_data.variations.item_variation_data.ordinal	integer	此項目變化的顯示順序。此值是唯讀的。
定價類型	objects.item_data.variations.item_variation_data.pricing_type	string	指出品項變化的價格是固定的還是在銷售時確定的。
總數	objects.item_data.variations.item_variation_data.price_money.amount	integer	貨幣的金額，以貨幣表示的貨幣的最小面額。例如，當貨幣為美元時，金額以美分為單位。貨幣金額可以是正數或負數。請參閱特定欄位描述，以判斷特定情況下符號的含義。
貨幣	objects.item_data.variations.item_variation_data.price_money.currency	string	貨幣類型，採用 ISO 4217 格式。例如，美元的貨幣代碼是美元。
相關物件	related_objects	array of object
類型	related_objects.type	string	此物件的類型。
ID	related_objects.id	string	Square 發行的唯一識別碼。
更新於	related_objects.updated_at	string	RFC 3339 格式的上次修改時間戳記
版本	related_objects.version	integer	物件的目前版本。
已刪除	related_objects.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
出現在所有地點	related_objects.present_at_all_locations	boolean	如果為 true，則此物件存在於所有位置（包括未來的位置），除非在 absent_at_location_ids 欄位中指定。如果為 false，則此物件不會出現在任何位置（包括未來的位置），除非在 present_at_location_ids 欄位中指定。如果未指定，則預設為 true。
名稱	related_objects.category_data.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
名稱	related_objects.tax_data.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
計算階段	related_objects.tax_data.calculation_phase	string	稅金是根據付款的小計還是總計計算。
包含類型	related_objects.tax_data.inclusion_type	string	稅收是附加稅還是全稅稅。
百分比	related_objects.tax_data.percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
已啟用	related_objects.tax_data.enabled	boolean	指出是否可以使用物件。

批次擷取訂單

作業識別碼：: OrderBatchRetrieve

依 ID 擷取一組訂單。如果指定的訂單 ID 不存在，則會忽略該 ID，而不是產生錯誤。

參數

名稱	機碼	必要	類型	Description
位置標識碼	location_id		string	位置識別碼。
訂單 ID	order_ids		array of string

傳回

名稱	路徑	類型	Description
訂單	orders	array of object
ID	orders.id	string	Square 發行的唯一識別碼。
位置標識碼	orders.location_id	string	位置的識別碼。
參考標識碼	orders.reference_id	string	選用的第二個 ID，用來將客戶設定檔與另一個系統中的實體建立關聯。
明細項目	orders.line_items	array of object
UID	orders.line_items.uid	string	Square在發票中產生的付款請求ID。
名稱	orders.line_items.name	string	人類可讀的名稱。
數量	orders.line_items.quantity	string	購買的數量，格式為十進位數。
總數	orders.line_items.base_price_money.amount	integer	金額。
貨幣	orders.line_items.base_price_money.currency	string	貨幣。
總數	orders.line_items.total_money.amount	integer	金額。
貨幣	orders.line_items.total_money.currency	string	貨幣。
總數	orders.total_money.amount	integer	金額。
貨幣	orders.total_money.currency	string	貨幣。

批次更新插入目錄物件

作業識別碼：: CatalogBatchUpsert

根據提供的物件清單建立或更新最多 10,000 個目標物件。目標物件會分組成批次，而每個批次都會以全有或全無的方式插入/更新。如果批次中的物件以某種方式格式錯誤，或違反資料庫限制，則包含該項目的整個批次將被忽略。不過，相同要求中的其他批次可能仍會成功。每個批次最多可包含 1,000 個物件，只要請求的物件總計數（項目、變化、修飾詞清單、折扣和稅金）不超過 10,000 個，就會依序處理批次。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
類型	type	string	此物件的類型。
ID	id	string	參考此物件的識別碼。
出現在所有地點	present_at_all_locations	boolean	如果為 true，則此物件存在於所有位置（包括未來的位置），除非在 absent_at_location_ids 欄位中指定。如果為 false，則此物件不會出現在任何位置（包括未來的位置），除非在 present_at_location_ids 欄位中指定。如果未指定，則預設為 true。
名稱	name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
Description	title	string	項目的描述。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
類別標識碼	category_id	string	項目類別的識別碼（如果有的話）。
稅務識別碼	tax_ids	array of string
類型	type	string	此物件的類型。每個物件類型在下面的對應 *_data 欄位中都有以結構化格式表示的預期屬性。
ID	id	string	參考此物件的識別碼。
出現在所有地點	present_at_all_locations	boolean	是否存在於所有地點。
項目 ID	item_id	string	項目的識別碼。
名稱	name	string	項目的名稱。
定價類型	pricing_type	string	定價類型。
總數	amount	integer	金額。
貨幣	currency	string	貨幣。
名稱	name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
名稱	name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
計算階段	calculation_phase	string	稅金是根據付款的小計還是總計計算。
包含類型	inclusion_type	string	稅收是附加稅還是全稅稅。
百分比	percentage	string	稅收的百分比，以十進制形式，使用“.”作為小數點分隔符，不帶“%”號。值 7.5 對應於 7.5%。
適用於自訂金額	applies_to_custom_amounts	boolean	如果為true，則該費用適用於輸入到Square Point of Sale應用程式中且未與特定CatalogItem相關聯的自訂金額。
已啟用	enabled	boolean	布林旗標，指出稅金是否在 Square 銷售點應用程式中顯示為已啟用（true）（false）。

傳回

名稱	路徑	類型	Description
物件	objects	array of object
類型	objects.type	string	此物件的類型。
ID	objects.id	string	Square 發行的唯一識別碼。
更新於	objects.updated_at	string	RFC 3339 格式的上次修改時間戳記
版本	objects.version	integer	物件的目前版本。
已刪除	objects.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
出現在所有地點	objects.present_at_all_locations	boolean	如果為 true，則此物件存在於所有位置（包括未來的位置），除非在 absent_at_location_ids 欄位中指定。如果為 false，則此物件不會出現在任何位置（包括未來的位置），除非在 present_at_location_ids 欄位中指定。如果未指定，則預設為 true。
名稱	objects.item_data.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
Description	objects.item_data.title	string	項目的描述。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
類別標識碼	objects.item_data.category_id	string	項目類別的識別碼（如果有的話）。
稅務識別碼	objects.item_data.tax_ids	array of string
Variations	objects.item_data.variations	array of object
類型	objects.item_data.variations.type	string	此物件的類型。每個物件類型在下面的對應 *_data 欄位中都有以結構化格式表示的預期屬性。
ID	objects.item_data.variations.id	string	參考此物件的識別碼。
更新於	objects.item_data.variations.updated_at	string	RFC 3339 格式的上次修改時間戳記
版本	objects.item_data.variations.version	integer	物件的版本。更新物件時，提供的版本必須與資料庫中的版本相符，否則寫入將因衝突而被拒絕。
已刪除	objects.item_data.variations.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
出現在所有地點	objects.item_data.variations.present_at_all_locations	boolean	物件存在的位置清單，即使present_at_all_locations為 false。這可能包括已停用的位置。
項目 ID	objects.item_data.variations.item_variation_data.item_id	string	具有此項目變化的物件 ID。
名稱	objects.item_data.variations.item_variation_data.name	string	此項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
序數	objects.item_data.variations.item_variation_data.ordinal	integer	此項目變化的顯示順序。此值是唯讀的。
定價類型	objects.item_data.variations.item_variation_data.pricing_type	string	指出品項變化的價格是固定的還是在銷售時確定的。
總數	objects.item_data.variations.item_variation_data.price_money.amount	integer	貨幣的金額，以貨幣表示的貨幣的最小面額。例如，當貨幣為美元時，金額以美分為單位。貨幣金額可以是正數或負數。請參閱特定欄位描述，以判斷特定情況下符號的含義。
貨幣	objects.item_data.variations.item_variation_data.price_money.currency	string	貨幣類型，採用 ISO 4217 格式。例如，美元的貨幣代碼是美元。
名稱	objects.category_data.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
名稱	objects.tax_data.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
計算階段	objects.tax_data.calculation_phase	string	稅金是根據付款的小計還是總計計算。
包含類型	objects.tax_data.inclusion_type	string	稅收是附加稅還是全稅稅。
百分比	objects.tax_data.percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
適用於自訂金額	objects.tax_data.applies_to_custom_amounts	boolean	如果為true，則該費用適用於輸入到Square Point of Sale應用程式中且未與特定CatalogItem相關聯的自訂金額。
已啟用	objects.tax_data.enabled	boolean	指出是否可以使用物件。
ID 對應	id_mappings	array of object
用戶端物件識別碼	id_mappings.client_object_id	string	用戶端為新 CatalogObject 提供的暫存 #-前置詞識別碼。
物件識別碼	id_mappings.object_id	string	伺服器建立的永久 ID。

批次變更庫存

作業識別碼：: InventoryBatchChange

將調整和盤點套用至提供的品項數量。成功時：傳回請求中參考的所有物件的目前計算計數。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
類型	type	string	此物件的類型。
參考標識碼	reference_id	string	選用的使用者定義參照 ID，可將此卡與外部系統中的另一個實體相關聯。
目錄物件識別碼	catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
State	state	string	相關品項數量的目前庫存狀態。
位置標識碼	location_id	string	接收此投標部分的收件人（商家除外）的位置 ID。
數量	quantity	string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
員工 ID	employee_id	string	負責實際盤點的員工的 Square 產生的 ID。
發生於	occurred_at	string	用戶端產生的 RFC 3339 格式時間戳記，指出檢查實體計數的時間。對於實體計數更新，occurred_at時間戳記不能早於 24 小時，也不能相對於請求時間的未來。
忽略不變的計數	ignore_unchanged_counts	boolean	指出如果數量自上次實體盤點以來保持不變，則是否應忽略目前的實體盤點。

傳回

名稱	路徑	類型	Description
計數	counts	array of object
目錄物件識別碼	counts.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
目錄物件類型	counts.catalog_object_type	string	所追蹤的 CatalogObject 類型。
State	counts.state	string	目前的狀態。
位置標識碼	counts.location_id	string	位置的識別碼。
數量	counts.quantity	string	受估計計數影響的項目數，以十進位字串形式。最多可支援小數點後 5 位數字。
計算時間	counts.calculated_at	string	RFC 3339 格式的時間戳記，指出何時收到影響預估計數的最新實體計數或調整。

接受爭議

作業識別碼：: DisputeAccept

接受爭議的損失。 Square 將爭議金額退還給持卡人，並將爭議狀態更新為已接受。 Square 從賣家的 Square 帳戶中扣除有爭議的金額。如果 Square 帳戶沒有足夠的資金，Square 會從相關的銀行帳戶中扣除。

參數

名稱	機碼	必要	類型	Description
爭議 ID	dispute_id	True	string	爭議的標識符。

傳回

名稱	路徑	類型	Description
ID	dispute.id	string	Square 發行的唯一識別碼。
總數	dispute.amount_money.amount	integer	金額。
貨幣	dispute.amount_money.currency	string	貨幣。
原因	dispute.reason	string	這個物件的原因。
State	dispute.state	string	目前的狀態。
到期日	dispute.due_at	string	下一個動作到期的時間，採用 RFC 3339 格式。
有爭議的付款	dispute.disputed_payments	array of object
付款標識碼	dispute.disputed_payments.payment_id	string	Square 產生的付款唯一 ID。
卡片品牌	dispute.card_brand	string	卡片的品牌。
創建於	dispute.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	dispute.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
品牌爭議編號	dispute.brand_dispute_id	string	卡片品牌系統中爭議的 ID，由卡片品牌產生。

提交證據

作業識別碼：: EvidenceSubmit

向持卡人的銀行提交證據。在提交證據之前，Square 會彙編所有可用的證據。這包括使用 CreateDisputeEvidenceFile 和 CreateDisputeEvidenceText 端點上傳的證據，以及 Square 自動提供的證據（如果可用）。

參數

名稱	機碼	必要	類型	Description
爭議 ID	dispute_id	True	string	爭議的標識符。

傳回

名稱	路徑	類型	Description
ID	dispute.id	string	Square 發行的唯一識別碼。
總數	dispute.amount_money.amount	integer	金額。
貨幣	dispute.amount_money.currency	string	貨幣。
原因	dispute.reason	string	這個物件的原因。
State	dispute.state	string	目前的狀態。
到期日	dispute.due_at	string	下一個動作到期的時間，採用 RFC 3339 格式。
有爭議的付款	dispute.disputed_payments	array of object
付款標識碼	dispute.disputed_payments.payment_id	string	Square 產生的付款唯一 ID。
卡片品牌	dispute.card_brand	string	卡片的品牌。
創建於	dispute.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	dispute.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
品牌爭議編號	dispute.brand_dispute_id	string	卡片品牌系統中爭議的 ID，由卡片品牌產生。

搜尋客戶

作業識別碼：: CustomerSearch

使用支援的查詢篩選器搜尋與Square帳戶相關聯的客戶設定檔。呼叫 SearchCustomers 而不使用任何明確查詢篩選器，會傳回根據given_name和family_name依字母順序排序的所有客戶設定檔。

參數

名稱	機碼	類型	Description
模糊的	fuzzy	string	使用模糊篩選器，以模糊方式選取其屬性符合指定查詢的客戶。使用模糊選項時，會將搜尋查詢記號化，然後每個查詢記號都必須在搜尋屬性中的某個位置相符。對於單一權杖查詢，這實際上與部分比對作業的行為相同。
價值觀	values	array of string
規則	rule	string	指出符合篩選條件的客戶設定檔是否應包含在結果中或從結果中排除。
開始於	start_at	string	RFC 3339 格式的日期時間值，指出時間範圍何時開始。
結束時間	end_at	string	RFC 3339 格式的日期時間值，指出時間範圍何時結束。
全部	all	array of string
領域	field	string	使用一或多個客戶屬性作為排序索引鍵，以排序搜尋的客戶設定檔。
訂單	order	string	指出應根據排序欄位值排序結果的順序。字串使用標準字母比較來決定順序。
限制	limit	integer	在單一頁面中傳回的結果數目限制。限制是建議性的 - 實作可能會傳回更多或更少的結果。如果提供的限制為負數、零或高於 1,000 的最大限制，則會忽略它。

傳回

名稱	路徑	類型	Description
客戶	customers	array of object
ID	customers.id	string	Square 發行的唯一識別碼。
創建於	customers.created_at	string	ISO 8601 格式的事件時間。
更新於	customers.updated_at	string	RFC 3339 格式的上次修改時間戳記
名字	customers.given_name	string	與客戶設定檔相關聯的給定（即名字）名稱。
姓	customers.family_name	string	與客戶設定檔相關聯的家族（即姓氏）名稱。
電子郵件地址	customers.email_address	string	與客戶設定檔相關聯的電子郵件地址。
地址行 1	customers.address.address_line_1	string	地址的第一行。
地址行 2	customers.address.address_line_2	string	地址的第二行（如果有的話）。
地區	customers.address.locality	string	地址所在的城市或城鎮。
行政區一級	customers.address.administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	customers.address.postal_code	string	地址的郵遞區號。
國家	customers.address.country	string	地址的國家/地區，採用 ISO 3166-1-alpha-2 格式。
電話號碼	customers.phone_number	string	與客戶設定檔相關聯的 11 位電話號碼。
參考標識碼	customers.reference_id	string	選用的第二個 ID，用來將客戶設定檔與另一個系統中的實體建立關聯。
電子郵件取消訂閱	customers.preferences.email_unsubscribed	boolean	指出客戶是否已取消訂閱行銷活動電子郵件。值為 true 表示客戶選擇退出目前 Square 賣家或所有 Square 賣家的電子郵件行銷。此值是客戶 API 中的唯讀值。
創作來源	customers.creation_source	string	建立來源代表用來建立客戶設定檔的方法。
群組標識碼	customers.group_ids	array of string
區段ID	customers.segment_ids	array of string
版本	customers.version	integer	物件的目前版本。
備註	customers.note	string	與客戶設定檔相關聯的自訂附註。
Cursor	cursor	string	在此端點的後續呼叫中包含分頁游標，以擷取與原始查詢相關聯的下一組結果。

搜尋發票

作業識別碼：: InvoiceSearch

從篩選器中指定的位置搜尋發票。

參數

名稱	機碼	類型	Description
位置 ID	location_ids	array of string
客戶 ID	customer_ids	array of string
領域	field	string	使用一或多個客戶屬性作為排序索引鍵，以排序搜尋的客戶設定檔。
訂單	order	string	指出應根據排序欄位值排序結果的順序。字串使用標準字母比較來決定順序。
限制	limit	integer	要傳回的發票數量上限（200 張是最大限制）。如果未提供，伺服器會使用預設的 100 張發票限制。

傳回

名稱	路徑	類型	Description
Invoices	invoices	array of object
ID	invoices.id	string	Square 發行的唯一識別碼。
版本	invoices.version	integer	物件的目前版本。
位置標識碼	invoices.location_id	string	位置的識別碼。
訂單編號	invoices.order_id	string	訂單的識別碼。
付款請求	invoices.payment_requests	array of object
UID	invoices.payment_requests.uid	string	Square在發票中產生的付款請求ID。
請求類型	invoices.payment_requests.request_type	string	識別付款請求類型。此類型定義如何確定付款請求金額。
到期日	invoices.payment_requests.due_date	string	付款要求的到期日（以發票的時區為單位），格式為 YYYY-MM-DD。
啟用小費	invoices.payment_requests.tipping_enabled	boolean	如果設定為 true，則 Square 託管的帳單頁面（帳單的public_url欄位）會為顧客提供支付小費的位置。
溫馨提示	invoices.payment_requests.reminders	array of object	提醒
UID	invoices.payment_requests.reminders.uid	string	Square 指派的識別碼，可唯一識別 InvoicePaymentRequest 內的提醒。
相對排程天數	invoices.payment_requests.reminders.relative_scheduled_days	integer	付款請求之前（負數）或之後（正數）傳送提醒due_date的天數。
Message	invoices.payment_requests.reminders.message	string	提醒訊息。
地位	invoices.payment_requests.reminders.status	string	提醒的狀態。
總數	invoices.payment_requests.computed_amount_money.amount	integer	金額。
貨幣	invoices.payment_requests.computed_amount_money.currency	string	貨幣。
總數	invoices.payment_requests.total_completed_amount_money.amount	integer	金額。
貨幣	invoices.payment_requests.total_completed_amount_money.currency	string	貨幣。
自動付款來源	invoices.payment_requests.automatic_payment_source	string	自動付款的付款方式。
請求百分比	invoices.payment_requests.percentage_requested	string	以百分比指定付款請求的金額。
卡片 ID	invoices.payment_requests.card_id	string	存檔的信用卡或簽帳金融卡的 ID，用於收取付款要求。
發票號碼	invoices.invoice_number	string	用戶友好的發票號碼。
Title	invoices.title	string	發票的標題。
Description	invoices.description	string	描述。
預定時間	invoices.scheduled_at	string	排程處理發票的時間戳記，採用 RFC 3339 格式。發票發布後，Square 會根據交付方式和付款請求設置在指定日期處理發票。
地位	invoices.status	string	此物件的目前驗證狀態。
Timezone	invoices.timezone	string	用於解譯發票上行事曆日期的時區，例如due_date。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
創建於	invoices.created_at	string	ISO 8601 格式的事件時間。
更新於	invoices.updated_at	string	RFC 3339 格式的上次修改時間戳記
客戶識別碼	invoices.primary_recipient.customer_id	string	要與卡片相關聯的客戶 ID。
名字	invoices.primary_recipient.given_name	string	收件人的給定（即名字）。
姓	invoices.primary_recipient.family_name	string	收件者的姓氏（即姓氏）。
電子郵件地址	invoices.primary_recipient.email_address	string	收件者的電子郵件地址。
電話號碼	invoices.primary_recipient.phone_number	string	收件者的電話號碼。
Card	invoices.accepted_payment_methods.card	boolean	指出是否接受信用卡或簽帳金融卡付款。
Square 禮品卡	invoices.accepted_payment_methods.square_gift_card	boolean	指出是否接受 Square 禮品卡付款。
銀行帳戶	invoices.accepted_payment_methods.bank_account	boolean	指出是否接受銀行轉帳付款。
自訂欄位	invoices.custom_fields	array of object
標籤	invoices.custom_fields.label	string	自訂欄位的標籤或標題。
價值觀	invoices.custom_fields.value	string	自訂欄位的文字。
放置	invoices.custom_fields.placement	string	發票上自訂欄位的位置
送貨方式	invoices.delivery_method	string	Square 用來向顧客傳送發票、提醒和收據的配送方式。
銷售或服務日期	invoices.sale_or_service_date	string	銷售日期或提供服務的日期，以 YYYY-MM-DD 格式。此欄位可用來指定發票上顯示的過去或未來日期。
公用網址	invoices.public_url	string	Square 代管的帳單頁面的網址。使用 PublishInvoice 端點發佈發票後，Square 會託管發票頁面，並在回應中傳回頁面 URL。
總數	invoices.next_payment_amount_money.amount	integer	金額。
貨幣	invoices.next_payment_amount_money.currency	string	貨幣。
Cursor	cursor	string	在此端點的後續呼叫中包含分頁游標，以擷取與原始查詢相關聯的下一組結果。

搜尋目錄物件

作業識別碼：: CatalogSearch

透過比對支援的搜尋屬性值（不包括項目或項目變化的自訂屬性值）來搜尋任何類型的 CatalogObject，以針對一或多個指定的查詢篩選條件。

參數

名稱	機碼	類型	Description
物件類型	object_types	array of string
屬性名稱	attribute_name	string	要搜尋的屬性名稱。
屬性前綴	attribute_prefix	string	搜尋屬性值的所需字首。
限制	limit	integer	在單一頁面中傳回的結果數目限制。限制是建議性的 - 實作可能會傳回更多或更少的結果。如果提供的限制為負數、零或高於 1,000 的最大限制，則會忽略它。

傳回

名稱	路徑	類型	Description
物件	objects	array of object
類型	objects.type	string	此物件的類型。
ID	objects.id	string	Square 發行的唯一識別碼。
更新於	objects.updated_at	string	RFC 3339 格式的上次修改時間戳記
版本	objects.version	integer	物件的目前版本。
已刪除	objects.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
出現在所有地點	objects.present_at_all_locations	boolean	如果為 true，則此物件存在於所有位置（包括未來的位置），除非在 absent_at_location_ids 欄位中指定。如果為 false，則此物件不會出現在任何位置（包括未來的位置），除非在 present_at_location_ids 欄位中指定。如果未指定，則預設為 true。
名稱	objects.item_data.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
Description	objects.item_data.title	string	項目的描述。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
類別標識碼	objects.item_data.category_id	string	項目類別的識別碼（如果有的話）。
產品類型	objects.item_data.product_type	string	產品類型查詢運算式會傳回具有指定產品類型的項目或項目變化。
稅務識別碼	objects.item_data.tax_ids	array of string
Variations	objects.item_data.variations	array of object
類型	objects.item_data.variations.type	string	此物件的類型。每個物件類型在下面的對應 *_data 欄位中都有以結構化格式表示的預期屬性。
ID	objects.item_data.variations.id	string	參考此物件的識別碼。
更新於	objects.item_data.variations.updated_at	string	RFC 3339 格式的上次修改時間戳記
版本	objects.item_data.variations.version	integer	物件的版本。更新物件時，提供的版本必須與資料庫中的版本相符，否則寫入將因衝突而被拒絕。
已刪除	objects.item_data.variations.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
出現在所有地點	objects.item_data.variations.present_at_all_locations	boolean	物件存在的位置清單，即使present_at_all_locations為 false。這可能包括已停用的位置。
項目 ID	objects.item_data.variations.item_variation_data.item_id	string	具有此項目變化的物件 ID。
名稱	objects.item_data.variations.item_variation_data.name	string	此項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
序數	objects.item_data.variations.item_variation_data.ordinal	integer	此項目變化的顯示順序。此值是唯讀的。
總數	objects.item_data.variations.item_variation_data.price_money.amount	integer	貨幣的金額，以貨幣表示的貨幣的最小面額。例如，當貨幣為美元時，金額以美分為單位。貨幣金額可以是正數或負數。請參閱特定欄位描述，以判斷特定情況下符號的含義。
貨幣	objects.item_data.variations.item_variation_data.price_money.currency	string	貨幣類型，採用 ISO 4217 格式。例如，美元的貨幣代碼是美元。
定價類型	objects.item_data.variations.item_variation_data.pricing_type	string	指出品項變化的價格是固定的還是在銷售時確定的。
可見度	objects.item_data.visibility	string	能見度。

搜尋終端結帳

作業識別碼：: TerminalSearchCheckouts

擷取由提出請求的帳戶所建立的終端機結帳請求的篩選清單。

參數

名稱	機碼	必要	類型	Description
限制	limit		integer	在單一頁面中傳回的結果數目限制。限制是建議性的 - 實作可能會傳回更多或更少的結果。如果提供的限制為負數、零或高於 1,000 的最大限制，則會忽略它。
地位	status		string	目前狀態。

傳回

名稱	路徑	類型	Description
結帳	checkouts	array of object
ID	checkouts.id	string	Square 發行的唯一識別碼。
總數	checkouts.amount_money.amount	integer	金額。
貨幣	checkouts.amount_money.currency	string	貨幣。
參考標識碼	checkouts.reference_id	string	選用的第二個 ID，用來將客戶設定檔與另一個系統中的實體建立關聯。
備註	checkouts.note	string	與客戶設定檔相關聯的自訂附註。
裝置標識碼	checkouts.device_options.device_id	string	此 TerminalCheckout 之裝置的唯一識別碼。
允許給小費	checkouts.device_options.tip_settings.allow_tipping	boolean	指出是否為此結帳啟用小費。預設為 False。
跳過收據畫面	checkouts.device_options.skip_receipt_screen	boolean	指示裝置略過收據畫面。預設為 False。
地位	checkouts.status	string	此物件的目前驗證狀態。
付款 ID	checkouts.payment_ids	array of string
創建於	checkouts.created_at	string	ISO 8601 格式的事件時間。
更新於	checkouts.updated_at	string	RFC 3339 格式的上次修改時間戳記
App ID	checkouts.app_id	string	建立結帳的應用程式識別碼。
截止日期持續時間	checkouts.deadline_duration	string	RFC 3339 持續時間，之後會自動取消結帳。 PENDING 的 TerminalCheckout 會自動取消，且取消原因為 TIMED_OUT。預設值：建立後 5 分鐘
Cursor	cursor	string	在此端點的後續呼叫中包含分頁游標，以擷取與原始查詢相關聯的下一組結果。

搜尋終端退款

作業識別碼：: TerminalSearchRefunds

擷取由提出請求的賣方建立的 Interac Terminal 退款請求的過濾清單。

參數

名稱	機碼	必要	類型	Description
限制	limit		integer	在單一頁面中傳回的結果數目限制。限制是建議性的 - 實作可能會傳回更多或更少的結果。如果提供的限制為負數、零或高於 1,000 的最大限制，則會忽略它。
地位	status		string	目前狀態。

傳回

名稱	路徑	類型	Description
退款	refunds	array of object
ID	refunds.id	string	Square 發行的唯一識別碼。
退款 ID	refunds.refund_id	string	此退款的唯一 ID，由 Square 產生。
付款標識碼	refunds.payment_id	string	付款的 ID。
總數	refunds.amount_money.amount	integer	金額。
貨幣	refunds.amount_money.currency	string	貨幣。
原因	refunds.reason	string	持卡人向銀行發起爭議的爭議原因。
裝置標識碼	refunds.device_id	string	使用此代碼之裝置的唯一識別碼。裝置配對時填入。
截止日期持續時間	refunds.deadline_duration	string	RFC 3339 持續時間，之後會自動取消結帳。 PENDING 的 TerminalCheckout 會自動取消，且取消原因為 TIMED_OUT。預設值：建立後 5 分鐘
地位	refunds.status	string	此物件的目前驗證狀態。
創建於	refunds.created_at	string	ISO 8601 格式的事件時間。
更新於	refunds.updated_at	string	RFC 3339 格式的上次修改時間戳記
App ID	refunds.app_id	string	建立結帳的應用程式識別碼。
卡片品牌	refunds.card.card_brand	string	卡片的品牌。
最後 4 名	refunds.card.last_4	string	卡號的最後 4 位數字。
到期月份	refunds.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年份	refunds.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	refunds.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
卡片類型	refunds.card.card_type	string	卡片的類型。
垃圾箱	refunds.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
訂單編號	refunds.order_id	string	訂單的識別碼。
位置標識碼	refunds.location_id	string	位置的識別碼。

搜尋訂單

作業識別碼：: OrderSearch

搜尋一或多個地點的所有訂單。訂單包括所有銷售、退貨和換貨，無論它們以何種方式或何時進入 Square 生態系統（例如銷售點、發票和 Connect API）。

參數

名稱	機碼	類型	Description
返回條目	return_entries	boolean	控制搜尋結果格式的布林值。如果為true，SearchOrders會傳回OrderEntry物件。如果為 false，則 SearchOrders 會傳回完整的訂單物件。
限制	limit	integer	在單一頁面中傳回的結果數目限制。限制是建議性的 - 實作可能會傳回更多或更少的結果。如果提供的限制為負數、零或高於 1,000 的最大限制，則會忽略它。
位置 ID	location_ids	array of string
開始於	start_at	string	RFC 3339 格式的日期時間值，指出時間範圍何時開始。
結束時間	end_at	string	RFC 3339 格式的日期時間值，指出時間範圍何時結束。
States	states	array of string
排序欄位	sort_field	string	要排序的欄位。
排序順序	sort_order	string	傳回結果的時間順序。

傳回

名稱	路徑	類型	Description
訂單條目	order_entries	array of object
訂單編號	order_entries.order_id	string	訂單的識別碼。
位置標識碼	order_entries.location_id	string	位置的識別碼。
版本	order_entries.version	integer	物件的目前版本。
Cursor	cursor	string	在此端點的後續呼叫中包含分頁游標，以擷取與原始查詢相關聯的下一組結果。

搜尋訂用帳戶

作業識別碼：: SubscriptionSearch

搜尋訂閱。結果會依訂閱建立日期依時間順序排序。如果要求指定多個位置 ID，端點會依位置 ID 排序結果，然後依每個位置內的建立日期排序結果。如果查詢中未提供位置，則會搜尋所有位置。

參數

名稱	機碼	類型
位置 ID	location_ids	array of string
客戶 ID	customer_ids	array of string
來源名稱	source_names	array of string

傳回

名稱	路徑	類型	Description
訂閱	subscriptions	array of object
ID	subscriptions.id	string	Square 發行的唯一識別碼。
位置標識碼	subscriptions.location_id	string	位置的識別碼。
方案標識碼	subscriptions.plan_id	string	相關聯訂閱方案的識別碼
客戶識別碼	subscriptions.customer_id	string	與帳戶相關聯之客戶的 Square 指派 ID。
開始日期	subscriptions.start_date	string	訂閱的開始日期，以 YYYY-MM-DD 格式。
取消日期	subscriptions.canceled_date	string	訂閱取消日期，以 YYYY-MM-DD 格式。
收費截止日期	subscriptions.charged_through_date	string	客戶開立訂用帳戶發票的日期，格式為 YYYY-MM-DD 格式。
地位	subscriptions.status	string	此物件的目前驗證狀態。
創建於	subscriptions.created_at	string	ISO 8601 格式的事件時間。
卡片 ID	subscriptions.card_id	string	向訂閱收費的客戶卡識別碼。
付款截止日期	subscriptions.paid_until_date	string	支付日期。
Timezone	subscriptions.timezone	string	用於解譯發票上行事曆日期的時區，例如due_date。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
名稱	subscriptions.source.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
稅率	subscriptions.tax_percentage	string	對訂閱計費時套用的稅額。
總數	subscriptions.price_override_money.amount	integer	金額。
貨幣	subscriptions.price_override_money.currency	string	貨幣。
版本	subscriptions.version	integer	物件的目前版本。
發票 ID	subscriptions.invoice_ids	array of string

擷取卡片

作業識別碼：: CardRetrieve

擷取特定卡片的詳細資料。

參數

名稱	機碼	必要	類型	Description
卡片 ID	card_id	True	string	卡片的識別碼。

傳回

名稱	路徑	類型	Description
ID	card.id	string	Square 發行的唯一識別碼。
地址行 1	card.billing_address.address_line_1	string	地址的第一行。以address_line開頭的欄位提供地址最具體的詳細信息，例如街道號碼、街道名稱和建築物名稱。
地址行 2	card.billing_address.address_line_2	string	地址的第二行（如果有的話）。
地區	card.billing_address.locality	string	地址所在的城市或城鎮。
行政區一級	card.billing_address.administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	card.billing_address.postal_code	string	地址的郵遞區號。
國家	card.billing_address.country	string	地址的國家/地區，採用 ISO 3166-1-alpha-2 格式。
指紋	card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
垃圾箱	card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
卡片品牌	card.card_brand	string	卡片的品牌。
卡片類型	card.card_type	string	卡片的類型。
持卡人姓名	card.cardholder_name	string	持卡人的姓名。
客戶識別碼	card.customer_id	string	此物件代表客戶的 ID。
已啟用	card.enabled	boolean	是否啟用。
到期月	card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	card.exp_year	integer	卡片到期日期的四位數年份。
最後 4 名	card.last_4	string	卡號的最後 4 位數字。
預付費類型	card.prepaid_type	string	指示卡片是否預付。
參考標識碼	card.reference_id	string	選用的使用者定義參照 ID。
版本	card.version	integer	此物件的目前版本。

擷取客戶

作業識別碼：: CustomerRetrieve

傳回單一客戶的詳細資料。

參數

名稱	機碼	必要	類型	Description
客戶識別碼	customer_id	True	string	客戶的識別碼。

傳回

名稱	路徑	類型	Description
ID	customer.id	string	Square 發行的唯一識別碼。
創建於	customer.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	customer.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
名字	customer.given_name	string	與客戶設定檔相關聯的給定（即名字）名稱。
姓	customer.family_name	string	與客戶設定檔相關聯的家族（即姓氏）名稱。
電子郵件地址	customer.email_address	string	與客戶設定檔相關聯的電子郵件地址。
地址行 1	customer.address.address_line_1	string	地址的第一行。以address_line開頭的欄位提供地址最具體的詳細信息，例如街道號碼、街道名稱和建築物名稱。
地址行 2	customer.address.address_line_2	string	地址的第二行（如果有的話）。
地區	customer.address.locality	string	地址所在的城市或城鎮。
行政區一級	customer.address.administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	customer.address.postal_code	string	地址的郵遞區號。
國家	customer.address.country	string	地址的國家/地區，採用 ISO 3166-1-alpha-2 格式。
電話號碼	customer.phone_number	string	與客戶設定檔相關聯的 11 位電話號碼。
參考標識碼	customer.reference_id	string	選用的使用者定義參照 ID。
備註	customer.note	string	與客戶設定檔相關聯的自訂附註。
電子郵件取消訂閱	customer.preferences.email_unsubscribed	boolean	指出客戶是否已取消訂閱行銷活動電子郵件。值為 true 表示客戶選擇退出目前 Square 賣家或所有 Square 賣家的電子郵件行銷。
創作來源	customer.creation_source	string	建立來源代表用來建立客戶設定檔的方法。
群組標識碼	customer.group_ids	array of string
區段ID	customer.segment_ids	array of string
版本	customer.version	integer	此物件的目前版本。

擷取客戶區段

作業識別碼：: CustomerSegmentRetrieve

擷取特定客戶區段。

參數

名稱	機碼	必要	類型	Description
區段識別碼	segment_id	True	string	區段的識別碼。

傳回

名稱	路徑	類型	Description
ID	segment.id	string	Square 發行的唯一識別碼。
名稱	segment.name	string	物件的名稱。
創建於	segment.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	segment.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。

擷取客戶群組

作業識別碼：: CustomerGroupRetrieve

擷取特定客戶群組。

參數

名稱	機碼	必要	類型	Description
群組識別碼	group_id	True	string	群組的識別碼。

傳回

名稱	路徑	類型	Description
ID	group.id	string	Square 發行的唯一識別碼。
名稱	group.name	string	物件的名稱。
創建於	group.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	group.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。

擷取庫存實體盤點

作業識別碼：: InventoryRetrievePhysicalCount

傳回 InventoryPhysicalCount 物件，其中包含提供physical_count_id。

參數

名稱	機碼	必要	類型	Description
實體計數 ID	physical_count_id	True	string	實體計數的識別碼。

傳回

名稱	路徑	類型	Description
ID	count.id	string	Square 發行的唯一識別碼。
參考標識碼	count.reference_id	string	選用的使用者定義參照 ID。
目錄物件識別碼	count.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
目錄物件類型	count.catalog_object_type	string	所追蹤的 CatalogObject 類型。
State	count.state	string	目前的狀態。
位置標識碼	count.location_id	string	位置的識別碼。
數量	count.quantity	string	受調整影響的項目數，以十進位字串形式表示。最多可支援小數點後 5 位數字。
Product	count.source.product	string	應用程式的產品類型。
應用程式識別碼	count.source.application_id	string	指派給應用程式的唯讀 Square ID。
名稱	count.source.name	string	名稱。
員工 ID	count.employee_id	string	員工的 Square 產生的 ID。
發生於	count.occurred_at	string	用戶端產生的 RFC 3339 格式時間戳記，指出庫存調整發生的時間。對於庫存調整更新，occurred_at時間戳記不能超過 24 小時或相對於請求時間的未來時間。
創建於	count.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。

擷取庫存盤點

作業識別碼：: InventoryRetrieveCount

擷取一組指定位置中指定 CatalogObject 的目前計算庫存計數。

參數

名稱	機碼	必要	類型	Description
目錄物件識別碼	catalog_object_id	True	string	目錄物件的識別碼。
位置 ID	location_ids		string	要以逗號分隔清單的形式查閱的位置 ID。空白清單會查詢所有位置。
Cursor	cursor		string	先前呼叫此端點所傳回的分頁游標。

傳回

名稱	路徑	類型	Description
計數	counts	array of object
目錄物件識別碼	counts.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
目錄物件類型	counts.catalog_object_type	string	所追蹤的 CatalogObject 類型。
State	counts.state	string	目前的狀態。
位置標識碼	counts.location_id	string	位置的識別碼。
數量	counts.quantity	string	受估計計數影響的項目數，以十進位字串形式。最多可支援小數點後 5 位數字。
計算時間	counts.calculated_at	string	RFC 3339 格式的時間戳記，指出何時收到影響預估計數的最新實體計數或調整。

擷取庫存調整

作業識別碼：: InventoryRetrieveAdjustment

傳回 InventoryAdjustment 物件，其中包含提供的adjustment_id。

參數

名稱	機碼	必要	類型	Description
調整ID	adjustment_id	True	string	調整的識別碼。

傳回

名稱	路徑	類型	Description
ID	adjustment.id	string	Square 發行的唯一識別碼。
參考標識碼	adjustment.reference_id	string	選用的使用者定義參照 ID。
來自狀態	adjustment.from_state	string	調整前相關數量項目的庫存狀態。
聲明	adjustment.to_state	string	調整後相關數量項目的庫存狀態。
位置標識碼	adjustment.location_id	string	位置的識別碼。
目錄物件識別碼	adjustment.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
目錄物件類型	adjustment.catalog_object_type	string	所追蹤的 CatalogObject 類型。
數量	adjustment.quantity	string	受調整影響的項目數，以十進位字串形式表示。最多可支援小數點後 5 位數字。
總數	adjustment.total_price_money.amount	integer	金額。
貨幣	adjustment.total_price_money.currency	string	貨幣。
發生於	adjustment.occurred_at	string	用戶端產生的 RFC 3339 格式時間戳記，指出庫存調整發生的時間。對於庫存調整更新，occurred_at時間戳記不能超過 24 小時或相對於請求時間的未來時間。
創建於	adjustment.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
Product	adjustment.source.product	string	應用程式的產品類型。
應用程式識別碼	adjustment.source.application_id	string	指派給應用程式的唯讀 Square ID。
名稱	adjustment.source.name	string	名稱。
員工 ID	adjustment.employee_id	string	員工的 Square 產生的 ID。

擷取庫存轉移（Beta 版）

作業識別碼：: InventoryRetrieveTransfer

傳回 InventoryTransfer 物件以及提供的transfer_id。

參數

名稱	機碼	必要	類型	Description
移轉識別碼	transfer_id	True	string	傳輸的識別碼。

傳回

名稱	路徑	類型	Description
ID	transfer.id	string	Square 發行的唯一識別碼。
目錄物件識別碼	transfer.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
目錄物件類型	transfer.catalog_object_type	string	所追蹤的 CatalogObject 類型。
創建於	transfer.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
員工 ID	transfer.employee_id	string	員工的 Square 產生的 ID。
從位置 ID	transfer.from_location_id	string	在轉移之前追蹤相關品項數量的位置的 Square 產生的 ID。
前往位置 ID	transfer.to_location_id	string	轉移後追蹤相關品項數量的位置的 Square 產生的 ID。
發生於	transfer.occurred_at	string	用戶端產生的 RFC 3339 格式時間戳記，指出庫存調整發生的時間。對於庫存調整更新，occurred_at時間戳記不能超過 24 小時或相對於請求時間的未來時間。
數量	transfer.quantity	string	受調整影響的項目數，以十進位字串形式表示。最多可支援小數點後 5 位數字。
參考標識碼	transfer.reference_id	string	選用的使用者定義參照 ID。
Product	transfer.source.product	string	應用程式的產品類型。
應用程式識別碼	transfer.source.application_id	string	指派給應用程式的唯讀 Square ID。
名稱	transfer.source.name	string	名稱。
State	transfer.state	string	目前的狀態。

擷取爭議

作業識別碼：: DisputeRetrieve

傳回特定爭議的詳細資料。

參數

名稱	機碼	必要	類型	Description
爭議 ID	dispute_id	True	string	爭議的標識符。

傳回

名稱	路徑	類型	Description
ID	dispute.id	string	Square 發行的唯一識別碼。
總數	dispute.amount_money.amount	integer	金額。
貨幣	dispute.amount_money.currency	string	貨幣。
原因	dispute.reason	string	這個物件的原因。
State	dispute.state	string	目前的狀態。
到期日	dispute.due_at	string	下一個動作到期的時間，採用 RFC 3339 格式。
有爭議的付款	dispute.disputed_payments	array of object
付款標識碼	dispute.disputed_payments.payment_id	string	Square 產生的付款唯一 ID。
卡片品牌	dispute.card_brand	string	卡片的品牌。
創建於	dispute.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	dispute.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
品牌爭議編號	dispute.brand_dispute_id	string	卡片品牌系統中爭議的 ID，由卡片品牌產生。

擷取爭議證據

作業識別碼：: DisputeRetrieveEvidence

傳回請求 URL 路徑中證據 ID 所指定的證據中繼資料。如果您想稍後參考，您必須保留上傳的證據副本。上傳證據後，您無法下載證據。

參數

名稱	機碼	必要	類型	Description
爭議 ID	dispute_id	True	string	爭議的標識符。
證據 ID	evidence_id	True	string	證據的識別碼。

傳回

名稱	路徑	類型	Description
ID	evidence.id	string	Square 發行的唯一識別碼。
爭議 ID	evidence.dispute_id	string	與證據相關聯的爭議 ID。
檔名	evidence.evidence_file.filename	string	爭議證據文件必須是 application/pdf、image/heic、image/heif、image/jpeg、image/png 或 image/tiff 格式。
檔案類型	evidence.evidence_file.filetype	string	檔案名稱，包括副檔名。
辨識項類型	evidence.evidence_type	string	類型 pf 證據。
上傳於	evidence.uploaded_at	string	下一個動作到期的時間，採用 RFC 3339 格式。

擷取目錄物件

作業識別碼：: CatalogRetrieve

根據提供的識別碼，將單一 CatalogItem 傳回為 CatalogObject。傳回的物件包含所有相關的 CatalogItem 資訊，包括：CatalogItemVariation 子系、其 CatalogModifierList 物件的參考，以及套用至它的任何 CatalogTax 物件的識別碼。

參數

名稱	機碼	必要	類型	Description
物件識別碼	object_id	True	string	物件的識別碼。
包含相關物件	include_related_objects		boolean	如果為 true，回應將包含與所要求物件相關的其他物件，如下所示：如果回應的物件欄位包含 CatalogItem，則會在回應的 related_objects 欄位中傳回其相關聯的 CatalogCategory、CatalogTax、CatalogImage 和 CatalogModifierList 物件。如果回應的物件欄位包含 CatalogItemVariation，則會在回應的related_objects欄位中傳回其父 CatalogItem。

傳回

名稱	路徑	類型	Description
類型	object.type	string	此物件的類型。
ID	object.id	string	Square 發行的唯一識別碼。
更新於	object.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
版本	object.version	integer	此物件的目前版本。
已刪除	object.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
present_at_all_locations	object.present_at_all_locations	boolean	如果為 true，則此物件存在於所有位置（包括未來的位置），除非在 absent_at_location_ids 欄位中指定。如果為 false，則此物件不會出現在任何位置（包括未來的位置），除非在 present_at_location_ids 欄位中指定。如果未指定，則預設為 true。
名稱	object.item_data.name	string	名稱。
Description	object.item_data.title	string	項目的描述。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
類別標識碼	object.item_data.category_id	string	項目類別的識別碼（如果有的話）。
稅務識別碼	object.item_data.tax_ids	array of string
Variations	object.item_data.variations	array of object
類型	object.item_data.variations.type	string	此物件的類型。
ID	object.item_data.variations.id	string	在型錄中參照此物件的識別碼。
更新於	object.item_data.variations.updated_at	string	RFC 3339 格式的上次修改時間戳記。
版本	object.item_data.variations.version	integer	物件的版本。更新物件時，提供的版本必須與資料庫中的版本相符，否則寫入將因衝突而被拒絕。
已刪除	object.item_data.variations.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
出現在所有地點	object.item_data.variations.present_at_all_locations	boolean	如果為 true，則此物件存在於所有位置（包括未來的位置），除非在 absent_at_location_ids 欄位中指定。如果為 false，則此物件不會出現在任何位置（包括未來的位置），除非在 present_at_location_ids 欄位中指定。如果未指定，則預設為 true。
項目 ID	object.item_data.variations.item_variation_data.item_id	string	與此專案變數相關聯的 CatalogItem 識別碼。
名稱	object.item_data.variations.item_variation_data.name	string	項目變化的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
序數	object.item_data.variations.item_variation_data.ordinal	integer	此項目變化的顯示順序。此值是唯讀的。寫入時，父 CatalogItem 內每個專案變數的序數會根據專案變數的位置來設定。在讀取時，不保證值是循序或唯一的。
定價類型	object.item_data.variations.item_variation_data.pricing_type	string	指出品項變化的價格是固定的還是在銷售時確定的。
總數	object.item_data.variations.item_variation_data.price_money.amount	integer	金額。
貨幣	object.item_data.variations.item_variation_data.price_money.currency	string	貨幣。

擷取訂單

作業識別碼：: OrderRetrieve

依 ID 擷取訂單。

參數

名稱	機碼	必要	類型	Description
訂單編號	order_id	True	string	訂單的識別碼。

傳回

名稱	路徑	類型	Description
ID	order.id	string	Square 發行的唯一識別碼。
位置標識碼	order.location_id	string	位置的識別碼。
明細項目	order.line_items	array of object
UID	order.line_items.uid	string	Square 產生的 ID。
數量	order.line_items.quantity	string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
名稱	order.line_items.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
總數	order.line_items.base_price_money.amount	integer	金額。
貨幣	order.line_items.base_price_money.currency	string	貨幣。
總數	order.line_items.gross_sales_money.amount	integer	金額。
貨幣	order.line_items.gross_sales_money.currency	string	貨幣。
總數	order.line_items.total_tax_money.amount	integer	金額。
貨幣	order.line_items.total_tax_money.currency	string	貨幣。
總數	order.line_items.total_discount_money.amount	integer	金額。
貨幣	order.line_items.total_discount_money.currency	string	貨幣。
總數	order.line_items.total_money.amount	integer	金額。
貨幣	order.line_items.total_money.currency	string	貨幣。
總數	order.line_items.variation_total_price_money.amount	integer	金額。
貨幣	order.line_items.variation_total_price_money.currency	string	貨幣。
適用折扣	order.line_items.applied_discounts	array of object
UID	order.line_items.applied_discounts.uid	string	Square 指派的 ID。
折扣 UID	order.line_items.applied_discounts.discount_uid	string	套用折扣所代表的折扣 uid。
總數	order.line_items.applied_discounts.applied_money.amount	integer	金額。
貨幣	order.line_items.applied_discounts.applied_money.currency	string	貨幣。
折扣	order.discounts	array of object
UID	order.discounts.uid	string	Square 產生的 ID。
名稱	order.discounts.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
百分比	order.discounts.percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
總數	order.discounts.applied_money.amount	integer	金額。
貨幣	order.discounts.applied_money.currency	string	貨幣。
類型	order.discounts.type	string	指出類型。
Scope	order.discounts.scope	string	指出目前的層級。
創建於	order.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	order.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
State	order.state	string	目前的狀態。
版本	order.version	integer	此物件的目前版本。
總數	order.total_tax_money.amount	integer	金額。
貨幣	order.total_tax_money.currency	string	貨幣。
總數	order.total_discount_money.amount	integer	金額。
貨幣	order.total_discount_money.currency	string	貨幣。
總數	order.total_tip_money.amount	integer	金額。
貨幣	order.total_tip_money.currency	string	貨幣。
總數	order.total_money.amount	integer	金額。
貨幣	order.total_money.currency	string	貨幣。
總數	order.total_service_charge_money.amount	integer	金額。
貨幣	order.total_service_charge_money.currency	string	貨幣。
總數	order.net_amounts.total_money.amount	integer	金額。
貨幣	order.net_amounts.total_money.currency	string	貨幣。
總數	order.net_amounts.tax_money.amount	integer	金額。
貨幣	order.net_amounts.tax_money.currency	string	貨幣。
總數	order.net_amounts.discount_money.amount	integer	金額。
貨幣	order.net_amounts.discount_money.currency	string	貨幣。
總數	order.net_amounts.tip_money.amount	integer	金額。
貨幣	order.net_amounts.tip_money.currency	string	貨幣。
總數	order.net_amounts.service_charge_money.amount	integer	金額。
貨幣	order.net_amounts.service_charge_money.currency	string	貨幣。

擷取訂閱

作業識別碼：: SubscriptionRetrieve

擷取訂用帳戶。

參數

名稱	機碼	必要	類型	Description
訂用帳戶識別碼	subscription_id	True	string	訂用帳戶的識別碼。

傳回

名稱	路徑	類型	Description
ID	subscription.id	string	Square 發行的唯一識別碼。
位置標識碼	subscription.location_id	string	位置的識別碼。
方案標識碼	subscription.plan_id	string	相關聯訂閱方案的識別碼。
客戶識別碼	subscription.customer_id	string	此物件代表客戶的 ID。
開始日期	subscription.start_date	string	訂閱的開始日期，以 YYYY-MM-DD 格式。
收費截止日期	subscription.charged_through_date	string	客戶開立訂用帳戶發票的日期，格式為 YYYY-MM-DD 格式。
地位	subscription.status	string	此物件的目前驗證狀態。
發票 ID	subscription.invoice_ids	array of string
總數	subscription.price_override_money.amount	integer	金額。
貨幣	subscription.price_override_money.currency	string	貨幣。
創建於	subscription.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
付款截止日期	subscription.paid_until_date	string	支付日期。
Timezone	subscription.timezone	string	用來解譯行事曆日期的時區。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
名稱	subscription.source.name	string	名稱。

更新付款

作業識別碼：: PaymentUpdate

將付款更新為「已核准」狀態。您可以使用此端點更新amount_money和tip_money。

參數

名稱	機碼	必要	類型	Description
付款標識碼	payment_id	True	string	付款的識別碼。
冪等金鑰	idempotency_key		string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
總數	amount		integer	金額。
貨幣	currency		string	貨幣。
總數	amount		integer	金額。
貨幣	currency		string	貨幣。
版本令牌	version_token		string	此不透明權杖可識別物件的特定版本。

傳回

名稱	路徑	類型	Description
ID	payment.id	string	Square 發行的唯一識別碼。
創建於	payment.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	payment.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
總數	payment.amount_money.amount	integer	金額。
貨幣	payment.amount_money.currency	string	貨幣。
總數	payment.tip_money.amount	integer	金額。
貨幣	payment.tip_money.currency	string	貨幣。
地位	payment.status	string	此物件的目前驗證狀態。
延遲持續時間	payment.delay_duration	string	建立付款後，Square 自動將delay_action套用至付款的持續時間。此自動delay_action僅適用於在delay_duration時段之前未達到終止狀態（COMPLETED、CANCELED 或 FAILED）的付款。此欄位以 RFC 3339 格式指定為持續時間。
來源類型	payment.source_type	string	此付款的來源類型。目前值包括 CARD、BANK_ACCOUNT、WALLET、CASH 或 EXTERNAL。
地位	payment.card_details.status	string	目前狀態。
卡片品牌	payment.card_details.card.card_brand	string	卡片的品牌。
最後 4 名	payment.card_details.card.last_4	string	卡號的最後 4 位數字。
到期月	payment.card_details.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	payment.card_details.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	payment.card_details.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
卡片類型	payment.card_details.card.card_type	string	卡片的類型。
預付費類型	payment.card_details.card.prepaid_type	string	指示卡片是否預付。
垃圾箱	payment.card_details.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
報名方式	payment.card_details.entry_method	string	用於輸入卡詳細信息以進行付款的方法。該方法可以是 KEYED、SWIPED、EMV、ON_FILE 或 CONTACTLESS。
CVV 狀態	payment.card_details.cvv_status	string	從卡片驗證值（CVV）檢查傳回的狀態碼。代碼可以是CVV_ACCEPTED、CVV_REJECTED或CVV_NOT_CHECKED。
AVS 狀態	payment.card_details.avs_status	string	從地址驗證系統（AVS）檢查傳回的狀態碼。代碼可以是AVS_ACCEPTED、AVS_REJECTED或AVS_NOT_CHECKED。
驗證結果代碼	payment.card_details.auth_result_code	string	發卡機構傳回的狀態碼，描述付款的授權狀態。
報表說明	payment.card_details.statement_description	string	傳送至卡片網路的報表說明。
授權於	payment.card_details.card_payment_timeline.authorized_at	string	授權付款的時間戳記，採用 RFC 3339 格式。
位置標識碼	payment.location_id	string	位置的識別碼。
訂單編號	payment.order_id	string	訂單的識別碼。
創建於	payment.risk_evaluation.created_at	string	建立時的時間戳記，採用 RFC 3339 格式。
風險等級	payment.risk_evaluation.risk_level	string	與付款相關聯的風險等級。
備註	payment.note	string	與客戶設定檔相關聯的自訂附註。
客戶識別碼	payment.customer_id	string	此物件代表客戶的 ID。
總數	payment.total_money.amount	integer	金額。
貨幣	payment.total_money.currency	string	貨幣。
總數	payment.approved_money.amount	integer	金額。
貨幣	payment.approved_money.currency	string	貨幣。
能力	payment.capabilities	array of string
收據號碼	payment.receipt_number	string	付款的收據號碼。如果取消付款，則會遺失此欄位。
延遲作	payment.delay_action	string	delay_duration過後要套用至付款的動作。
延遲至	payment.delayed_until	string	自動套用delay_action時的唯讀時間戳記，採用 RFC 3339 格式。
方形產品	payment.application_details.square_product	string	Square 產品，例如 Square 銷售點（POS）、Square 發票或 Square 虛擬終端機。
應用程式識別碼	payment.application_details.application_id	string	指派給應用程式的唯讀 Square ID。
版本令牌	payment.version_token	string	此不透明權杖可識別物件的特定版本。

更新客戶

作業識別碼：: CustomerUpdate

更新客戶設定檔。若要變更屬性，請指定新值。若要移除屬性，請將值指定為空字串或空物件。

參數

名稱	機碼	必要	類型	Description
客戶識別碼	customer_id	True	string	客戶的識別碼。

傳回

名稱	路徑	類型	Description
ID	customer.id	string	Square 發行的唯一識別碼。
創建於	customer.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	customer.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
名字	customer.given_name	string	與客戶設定檔相關聯的給定（即名字）名稱。
姓	customer.family_name	string	與客戶設定檔相關聯的家族（即姓氏）名稱。
電子郵件地址	customer.email_address	string	與客戶設定檔相關聯的電子郵件地址。
地址行 1	customer.address.address_line_1	string	地址的第一行。以address_line開頭的欄位提供地址最具體的詳細信息，例如街道號碼、街道名稱和建築物名稱。
地址行 2	customer.address.address_line_2	string	地址的第二行（如果有的話）。
地區	customer.address.locality	string	地址所在的城市或城鎮。
行政區一級	customer.address.administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	customer.address.postal_code	string	地址的郵遞區號。
國家	customer.address.country	string	地址的國家/地區，採用 ISO 3166-1-alpha-2 格式。
參考標識碼	customer.reference_id	string	選用的使用者定義參照 ID。
備註	customer.note	string	與客戶設定檔相關聯的自訂附註。
電子郵件取消訂閱	customer.preferences.email_unsubscribed	boolean	指出客戶是否已取消訂閱行銷活動電子郵件。值為 true 表示客戶選擇退出目前 Square 賣家或所有 Square 賣家的電子郵件行銷。
創作來源	customer.creation_source	string	建立來源代表用來建立客戶設定檔的方法。
版本	customer.version	integer	此物件的目前版本。

更新客戶群組

作業識別碼：: CustomerGroupUpdate

更新客戶群組。

參數

名稱	機碼	必要	類型	Description
群組識別碼	group_id	True	string	群組的識別碼。
名稱	name		string	物件的名稱。

傳回

名稱	路徑	類型	Description
ID	group.id	string	Square 發行的唯一識別碼。
名稱	group.name	string	物件的名稱。
創建於	group.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	group.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。

更新插入目錄物件

作業識別碼：: CatalogUpsert

建立或更新目標 CatalogObject。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
ID	id	string	Square 發行的唯一識別碼。
類型	type	string	此物件的類型。
Abbreviation	abbreviation	string	Square 銷售點應用程式中商品顯示標籤的文字。最多只使用字串的前五個字元。此屬性是可搜尋的，其值長度是 Unicode 字碼點。
Description	title	string	項目的描述。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
名稱	name	string	名稱。
ID	id	string	在型錄中參照此物件的識別碼。
類型	type	string	此物件的類型。
項目 ID	item_id	string	與此專案變數相關聯的 CatalogItem 識別碼。
名稱	name	string	項目變化的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
定價類型	pricing_type	string	指出品項變化的價格是固定的還是在銷售時確定的。
總數	amount	integer	金額。
貨幣	currency	string	貨幣。

傳回

名稱	路徑	類型	Description
類型	catalog_object.type	string	此物件的類型。
ID	catalog_object.id	string	Square 發行的唯一識別碼。
更新於	catalog_object.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
版本	catalog_object.version	integer	此物件的目前版本。
已刪除	catalog_object.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
present_at_all_locations	catalog_object.present_at_all_locations	boolean	如果為 true，則此物件存在於所有位置（包括未來的位置），除非在 absent_at_location_ids 欄位中指定。如果為 false，則此物件不會出現在任何位置（包括未來的位置），除非在 present_at_location_ids 欄位中指定。如果未指定，則預設為 true。
名稱	catalog_object.item_data.name	string	名稱。
Description	catalog_object.item_data.title	string	項目的描述。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
Abbreviation	catalog_object.item_data.abbreviation	string	Square 銷售點應用程式中商品顯示標籤的文字。最多只使用字串的前五個字元。此屬性是可搜尋的，其值長度是 Unicode 字碼點。
Variations	catalog_object.item_data.variations	array of object
類型	catalog_object.item_data.variations.type	string	此物件的類型。
ID	catalog_object.item_data.variations.id	string	在型錄中參照此物件的識別碼。
更新於	catalog_object.item_data.variations.updated_at	string	RFC 3339 格式的上次修改時間戳記。
版本	catalog_object.item_data.variations.version	integer	物件的版本。更新物件時，提供的版本必須與資料庫中的版本相符，否則寫入將因衝突而被拒絕。
已刪除	catalog_object.item_data.variations.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
出現在所有地點	catalog_object.item_data.variations.present_at_all_locations	boolean	如果為 true，則此物件存在於所有位置（包括未來的位置），除非在 absent_at_location_ids 欄位中指定。如果為 false，則此物件不會出現在任何位置（包括未來的位置），除非在 present_at_location_ids 欄位中指定。如果未指定，則預設為 true。
項目 ID	catalog_object.item_data.variations.item_variation_data.item_id	string	與此專案變數相關聯的 CatalogItem 識別碼。
名稱	catalog_object.item_data.variations.item_variation_data.name	string	項目變化的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值長度是 Unicode 字碼點。
序數	catalog_object.item_data.variations.item_variation_data.ordinal	integer	此項目變化的顯示順序。此值是唯讀的。寫入時，父 CatalogItem 內每個專案變數的序數會根據專案變數的位置來設定。在讀取時，不保證值是循序或唯一的。
定價類型	catalog_object.item_data.variations.item_variation_data.pricing_type	string	指出品項變化的價格是固定的還是在銷售時確定的。
可庫存	catalog_object.item_data.variations.item_variation_data.stockable	boolean	庫存是直接計算在此變化（TRUE）還是僅計算其組件（FALSE）。為了回溯相容性，遺漏值會解譯為 TRUE。
總數	catalog_object.item_data.variations.item_variation_data.price_money.amount	integer	金額。
貨幣	catalog_object.item_data.variations.item_variation_data.price_money.currency	string	貨幣。
產品類型	catalog_object.item_data.product_type	string	項目的產品類型。一旦創建了項目，就不能更改。
ID 對應	id_mappings	array of object
用戶端物件識別碼	id_mappings.client_object_id	string	用戶端為新 CatalogObject 提供的暫存 #-前置詞識別碼。
物件識別碼	id_mappings.object_id	string	伺服器建立的永久 ID。

更新發票

作業識別碼：: InvoiceUpdate

透過修改欄位、清除欄位或兩者來更新發票。

參數

名稱	機碼	必要	類型	Description
發票識別碼	invoice_id	True	string	發票的識別碼。
冪等金鑰	idempotency_key		string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
UID	uid		string	Square 產生的 ID。
啟用小費	tipping_enabled		boolean	如果設定為 true，則為客戶提供支付小費的位置。
要清除的欄位	fields_to_clear		array of string

傳回

名稱	路徑	類型	Description
ID	invoice.id	string	Square 發行的唯一識別碼。
版本	invoice.version	integer	此物件的目前版本。
位置標識碼	invoice.location_id	string	位置的識別碼。
訂單編號	invoice.order_id	string	訂單的識別碼。
付款請求	invoice.payment_requests	array of object
UID	invoice.payment_requests.uid	string	Square 產生的 ID。
請求類型	invoice.payment_requests.request_type	string	識別付款請求類型。此類型定義如何確定付款請求金額。
到期日	invoice.payment_requests.due_date	string	付款要求的到期日，以 YYYY-MM-DD 格式。
啟用小費	invoice.payment_requests.tipping_enabled	boolean	如果設定為 true，則為客戶提供支付小費的位置。
總數	invoice.payment_requests.computed_amount_money.amount	integer	金額。
貨幣	invoice.payment_requests.computed_amount_money.currency	string	貨幣。
總數	invoice.payment_requests.total_completed_amount_money.amount	integer	金額。
貨幣	invoice.payment_requests.total_completed_amount_money.currency	string	貨幣。
自動付款來源	invoice.payment_requests.automatic_payment_source	string	自動付款的付款方式。
發票號碼	invoice.invoice_number	string	用戶友好的發票號碼。該值在位置內是唯一的。如果在建立發票時未提供，Square 會指派一個值。
Title	invoice.title	string	標題。
Description	invoice.description	string	描述。
預定時間	invoice.scheduled_at	string	排程處理時的時間戳記，採用 RFC 3339 格式。
地位	invoice.status	string	此物件的目前驗證狀態。
Timezone	invoice.timezone	string	用來解譯行事曆日期的時區。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
創建於	invoice.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	invoice.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
客戶識別碼	invoice.primary_recipient.customer_id	string	與訂單相關聯的客戶識別碼。
名字	invoice.primary_recipient.given_name	string	收件人的給定（即名字）。
姓	invoice.primary_recipient.family_name	string	收件者的姓氏（即姓氏）。
電子郵件地址	invoice.primary_recipient.email_address	string	收件者的電子郵件地址。
電話號碼	invoice.primary_recipient.phone_number	string	收件者的電話號碼。
總數	invoice.next_payment_amount_money.amount	integer	金額。
貨幣	invoice.next_payment_amount_money.currency	string	貨幣。
Card	invoice.accepted_payment_methods.card	boolean	指出是否接受信用卡或簽帳金融卡付款。
Square 禮品卡	invoice.accepted_payment_methods.square_gift_card	boolean	指出是否接受 Square 禮品卡付款。
銀行帳戶	invoice.accepted_payment_methods.bank_account	boolean	指出是否接受銀行轉帳付款。
自訂欄位	invoice.custom_fields	array of object
標籤	invoice.custom_fields.label	string	自訂欄位的標籤或標題。
價值觀	invoice.custom_fields.value	string	自訂欄位的文字。
放置	invoice.custom_fields.placement	string	發票上自訂欄位的位置。
送貨方式	invoice.delivery_method	string	Square 用來向顧客傳送發票、提醒和收據的配送方式。發票發布後，Square 會根據交付方式和付款請求設置處理發票，可以立即處理發票，也可以在scheduled_at日期處理發票（如果指定）。
銷售或服務日期	invoice.sale_or_service_date	string	銷售日期或提供服務的日期，以 YYYY-MM-DD 格式。此欄位可用來指定發票上顯示的過去或未來日期。

更新訂閱

作業識別碼：: SubscriptionUpdate

更新訂閱。您可以設定、修改及清除訂閱欄位值。

參數

名稱	機碼	必要	類型	Description
訂用帳戶識別碼	subscription_id	True	string	訂用帳戶的識別碼。
版本	version		integer	此物件的目前版本。
稅率	tax_percentage		string	對訂閱計費時套用的稅額。
總數	amount		integer	金額。
貨幣	currency		string	貨幣。

傳回

名稱	路徑	類型	Description
ID	subscription.id	string	Square 發行的唯一識別碼。
位置標識碼	subscription.location_id	string	位置的識別碼。
方案標識碼	subscription.plan_id	string	相關聯訂閱方案的識別碼。
客戶識別碼	subscription.customer_id	string	此物件代表客戶的 ID。
地位	subscription.status	string	此物件的目前驗證狀態。
總數	subscription.price_override_money.amount	integer	金額。
貨幣	subscription.price_override_money.currency	string	貨幣。
版本	subscription.version	integer	此物件的目前版本。
創建於	subscription.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
Timezone	subscription.timezone	string	用來解譯行事曆日期的時區。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
名稱	subscription.source.name	string	名稱。

更新項目修飾符清單

作業識別碼：: CatalogUpdateModifier

更新套用至目標 CatalogItem 的 CatalogModifierList 物件，而不需要對整個專案執行更新插入。

參數

名稱	機碼	類型
項目 ID	item_ids	array of string
要啟用的修飾詞清單	modifier_lists_to_enable	array of string
要停用的修飾詞清單	modifier_lists_to_disable	array of string

傳回

名稱	路徑	類型	Description
更新於	updated_at	string	此更新的資料庫時間戳記，採用 RFC 3339 格式。

更新項目稅金

作業識別碼：: CatalogUpdateTaxes

更新套用至目標 CatalogItem 的 CatalogTax 物件，而不需要對整個項目執行更新插入。

參數

名稱	機碼	類型
項目 ID	item_ids	array of string
啟用的稅金	taxes_to_enable	array of string
要停用的稅金	taxes_to_disable	array of string

傳回

名稱	路徑	類型	Description
更新於	updated_at	string	此更新的資料庫時間戳記，採用 RFC 3339 格式。

更新順序（Beta 版）

作業識別碼：: OrderUpdate

透過新增、取代或刪除欄位來更新未結訂單。狀態為「已完成」或「已取消」的訂單無法更新。

參數

名稱	機碼	必要	類型	Description
訂單編號	order_id	True	string	訂單的識別碼。
冪等金鑰	idempotency_key		string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
版本	version		integer	此物件的目前版本。
UID	uid		string	Square 產生的 ID。
數量	quantity		string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
名稱	name		string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
總數	amount		integer	金額。
貨幣	currency		string	貨幣。
要清除的欄位	fields_to_clear		array of string

傳回

名稱	路徑	類型	Description
版本	order.version	integer	此物件的目前版本。
貨幣	order.total_money.currency	string	貨幣。
總數	order.total_money.amount	integer	金額。
名稱	order.source.name	string	名稱。
明細項目	order.line_items	array of object
貨幣	order.line_items.total_tax_money.currency	string	貨幣。
總數	order.line_items.total_tax_money.amount	integer	金額。
總數	order.line_items.total_money.amount	integer	金額。
貨幣	order.line_items.total_money.currency	string	貨幣。
總數	order.line_items.gross_sales_money.amount	integer	金額。
貨幣	order.line_items.gross_sales_money.currency	string	貨幣。
總數	order.line_items.base_price_money.amount	integer	金額。
貨幣	order.line_items.base_price_money.currency	string	貨幣。
數量	order.line_items.quantity	string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
貨幣	order.line_items.total_discount_money.currency	string	貨幣。
總數	order.line_items.total_discount_money.amount	integer	金額。
名稱	order.line_items.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
UID	order.line_items.uid	string	Square 產生的 ID。
總數	order.line_items.variation_total_price_money.amount	integer	金額。
貨幣	order.line_items.variation_total_price_money.currency	string	貨幣。
State	order.state	string	目前的狀態。
總數	order.total_service_charge_money.amount	integer	金額。
貨幣	order.total_service_charge_money.currency	string	貨幣。
ID	order.id	string	Square 發行的唯一識別碼。
位置標識碼	order.location_id	string	位置的識別碼。
總數	order.total_tax_money.amount	integer	金額。
貨幣	order.total_tax_money.currency	string	貨幣。
創建於	order.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
總數	order.total_discount_money.amount	integer	金額。
貨幣	order.total_discount_money.currency	string	貨幣。
貨幣	order.net_amounts.service_charge_money.currency	string	貨幣。
總數	order.net_amounts.service_charge_money.amount	integer	金額。
總數	order.net_amounts.total_money.amount	integer	金額。
貨幣	order.net_amounts.total_money.currency	string	貨幣。
貨幣	order.net_amounts.discount_money.currency	string	貨幣。
總數	order.net_amounts.discount_money.amount	integer	金額。
貨幣	order.net_amounts.tax_money.currency	string	貨幣。
總數	order.net_amounts.tax_money.amount	integer	金額。
更新於	order.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。

清單卡片

作業識別碼：: CardList

擷取提出要求的帳戶所擁有的卡片清單。

參數

名稱	機碼	類型	Description
Cursor	cursor	string	先前呼叫此端點所傳回的分頁游標。
客戶識別碼	customer_id	string	將結果限制為與提供的客戶相關聯的卡片。默認情況下，商家擁有的所有卡都會被退回。
包括已停用	include_disabled	boolean	包括殘疾人卡。預設情況下，會傳回商家擁有的所有已啟用的卡片。
參考標識碼	reference_id	string	將結果限制為與所提供reference_id相關聯的卡片。
排序順序	sort_order	string	依照以指定順序建立卡片的時間來排序傳回的清單。

傳回

名稱	路徑	類型	Description
Cards	cards	array of object
ID	cards.card.id	string	物件的識別碼
地址行 1	cards.card.billing_address.address_line_1	string	以address_line開頭的欄位提供地址最具體的詳細信息，例如街道號碼、街道名稱和建築物名稱。
地址行 2	cards.card.billing_address.address_line_2	string	地址的第二行（如果有的話）。
地區	cards.card.billing_address.locality	string	地址所在的城市或城鎮。
行政區一級	cards.card.billing_address.administrative_district_level_1	string	地址所在國家/地區內的民間實體。在美國，這就是州。
郵遞區號	cards.card.billing_address.postal_code	string	地址的郵遞區號。
國家	cards.card.billing_address.country	string	地址的國家/地區，採用 ISO 3166-1-alpha-2 格式。
指紋	cards.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
垃圾箱	cards.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
卡片品牌	cards.card.card_brand	string	卡片的品牌。
卡片類型	cards.card.card_type	string	卡片的類型。
持卡人姓名	cards.card.cardholder_name	string	持卡人的姓名。
客戶識別碼	cards.card.customer_id	string	要與卡片相關聯的客戶 ID。
已啟用	cards.card.enabled	boolean	指出是否可以使用物件。
到期月份	cards.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年份	cards.card.exp_year	integer	卡片到期日期的四位數年份。
最後 4 名	cards.card.last_4	string	卡號的最後 4 位數字。
預付費類型	cards.card.prepaid_type	string	指示卡片是否預付。
參考標識碼	cards.card.reference_id	string	選用的使用者定義參照 ID，可將此卡與外部系統中的另一個實體相關聯。
版本	cards.card.version	integer	卡片的目前版本號碼。隨著每次卡片更新而遞增。除非要求中的版本符合卡片的目前版本，否則更新現有卡片物件的要求將會遭到拒絕。

清單目錄

作業識別碼：: CatalogList

傳回 CatalogObjects 清單，其中包含目錄中一組所需類型的所有物件（例如，所有 CatalogItem 和 CatalogTax 物件）。 ListCatalog 不會傳回已刪除的目錄項目。

參數

名稱	機碼	必要	類型	Description
Cursor	cursor		integer	先前呼叫此端點所傳回的分頁游標。
型別	types		string	選擇性不區分大小寫、以逗號分隔的物件類型清單。有效值定義在 CatalogObjectType 列舉中，包括 ITEM、ITEM_VARIATION、CATEGORY、DISCOUNT、TAX、MODIFIER、MODIFIER_LIST 或 IMAGE。如果未指定，則作業會傳回用於提出請求的 Square API 版本的所有類型的物件。

傳回

名稱	路徑	類型	Description
物件	objects	array of object
類型	objects.type	string	此物件的類型。
ID	objects.id	string	Square 發行的唯一識別碼。
更新於	objects.updated_at	string	RFC 3339 格式的上次修改時間戳記
版本	objects.version	integer	物件的目前版本。
已刪除	objects.is_deleted	boolean	如果為true，則物件已從資料庫中刪除。對於要插入的新物件，必須為 false。刪除時，updated_at欄位將等於刪除時間。
出現在所有地點	objects.present_at_all_locations	boolean	如果為 true，則此物件存在於所有位置（包括未來的位置），除非在 absent_at_location_ids 欄位中指定。如果為 false，則此物件不會出現在任何位置（包括未來的位置），除非在 present_at_location_ids 欄位中指定。如果未指定，則預設為 true。
名稱	objects.category_data.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
名稱	objects.tax_data.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
計算階段	objects.tax_data.calculation_phase	string	稅金是根據付款的小計還是總計計算。
包含類型	objects.tax_data.inclusion_type	string	稅收是附加稅還是全稅稅。
百分比	objects.tax_data.percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
已啟用	objects.tax_data.enabled	boolean	指出是否可以使用物件。

獲得付款退款

作業識別碼：: RefundGet

使用refund_id擷取特定退款。

參數

名稱	機碼	必要	類型	Description
退款 ID	refund_id	True	string	退款的識別碼。

傳回

名稱	路徑	類型	Description
ID	refund.id	string	Square 發行的唯一識別碼。
地位	refund.status	string	此物件的目前驗證狀態。
總數	refund.amount_money.amount	integer	金額。
貨幣	refund.amount_money.currency	string	貨幣。
付款標識碼	refund.payment_id	string	付款的唯一 ID。
訂單編號	refund.order_id	string	訂單的識別碼。
創建於	refund.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	refund.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
手續費	refund.processing_fee	array of object
有效於	refund.processing_fee.effective_at	string	費用生效的時間戳記，採用 RFC 3339 格式。
類型	refund.processing_fee.type	string	指出類型。
總數	refund.processing_fee.amount_money.amount	integer	金額。
貨幣	refund.processing_fee.amount_money.currency	string	貨幣。
位置標識碼	refund.location_id	string	位置的識別碼。
原因	refund.reason	string	這個物件的原因。

獲得終端退款

作業識別碼：: TerminalGetRefund

依 ID 擷取 Interac 終端機退款物件。

參數

名稱	機碼	必要	類型	Description
終端退款 ID	terminal_refund_id	True	string	終端機退款的識別碼。

傳回

名稱	路徑	類型	Description
ID	refund.id	string	Square 發行的唯一識別碼。
退款 ID	refund.refund_id	string	此退款的唯一 ID，由 Square 產生。
付款標識碼	refund.payment_id	string	付款的唯一 ID。
總數	refund.amount_money.amount	integer	金額。
貨幣	refund.amount_money.currency	string	貨幣。
原因	refund.reason	string	這個物件的原因。
裝置標識碼	refund.device_id	string	用於此終端機退款的裝置的唯一 ID。
截止日期持續時間	refund.deadline_duration	string	RFC 3339 持續時間，之後會自動取消結帳。 PENDING 的 TerminalCheckout 會自動取消，且取消原因為 TIMED_OUT。預設值：建立後 5 分鐘
地位	refund.status	string	此物件的目前驗證狀態。
創建於	refund.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	refund.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
App ID	refund.app_id	string	建立結帳的應用程式識別碼。
卡片品牌	refund.card.card_brand	string	卡片的品牌。
last_4	refund.card.last_4	string	卡號的最後 4 位數字。
到期月	refund.card.exp_month	integer	關聯卡的到期月份，介於 1 到 12 之間的整數。
到期年	refund.card.exp_year	integer	卡片到期日期的四位數年份。
指紋	refund.card.fingerprint	string	旨在作為 Square 分配的標識符，基於卡號，用於在單個應用程序中的多個位置識別卡。
卡片類型	refund.card.card_type	string	卡片的類型。
垃圾箱	refund.card.bin	string	卡號的前六位數字，稱為銀行識別號（BIN）。
訂單編號	refund.order_id	string	訂單的識別碼。
位置標識碼	refund.location_id	string	位置的識別碼。

發佈發票

作業識別碼：: InvoicePublish

發佈指定的草稿發票。發票發布後，Square 會根據發票配置進行跟進。例如，Square 將發票發送到客戶的電子郵件地址，向客戶存檔的卡收費，或者什麼都不做。 Square 也會在 Square 託管的帳單頁面上提供帳單。

參數

名稱	機碼	必要	類型	Description
發票識別碼	invoice_id	True	string	發票的識別碼。
版本	version		integer	版本。
冪等金鑰	idempotency_key		string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。

傳回

名稱	路徑	類型	Description
ID	invoice.id	string	Square 發行的唯一識別碼。
版本	invoice.version	integer	此物件的目前版本。
位置標識碼	invoice.location_id	string	位置的識別碼。
訂單編號	invoice.order_id	string	訂單的識別碼。
付款請求	invoice.payment_requests	array of object
UID	invoice.payment_requests.uid	string	Square 產生的 ID。
請求類型	invoice.payment_requests.request_type	string	識別付款請求類型。此類型定義如何確定付款請求金額。
到期日	invoice.payment_requests.due_date	string	付款要求的到期日，以 YYYY-MM-DD 格式。
啟用小費	invoice.payment_requests.tipping_enabled	boolean	如果設定為 true，則為客戶提供支付小費的位置。
提醒	invoice.payment_requests.reminders	array of object
UID	invoice.payment_requests.reminders.uid	string	Square 指派的 ID。
相對排程天數	invoice.payment_requests.reminders.relative_scheduled_days	integer	付款請求之前（負數）或之後（正數）傳送提醒due_date的天數。
Message	invoice.payment_requests.reminders.message	string	訊息。
地位	invoice.payment_requests.reminders.status	string	目前狀態。
總數	invoice.payment_requests.computed_amount_money.amount	integer	金額。
貨幣	invoice.payment_requests.computed_amount_money.currency	string	貨幣。
總數	invoice.payment_requests.total_completed_amount_money.amount	integer	金額。
貨幣	invoice.payment_requests.total_completed_amount_money.currency	string	貨幣。
自動付款來源	invoice.payment_requests.automatic_payment_source	string	自動付款的付款方式。
發票號碼	invoice.invoice_number	string	用戶友好的發票號碼。該值在位置內是唯一的。如果在建立發票時未提供，Square 會指派一個值。
Title	invoice.title	string	標題。
Description	invoice.description	string	描述。
預定時間	invoice.scheduled_at	string	排程處理時的時間戳記，採用 RFC 3339 格式。
地位	invoice.status	string	此物件的目前驗證狀態。
Timezone	invoice.timezone	string	用來解譯行事曆日期的時區。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
創建於	invoice.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	invoice.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
客戶識別碼	invoice.primary_recipient.customer_id	string	與訂單相關聯的客戶識別碼。
名字	invoice.primary_recipient.given_name	string	收件人的給定（即名字）。
姓	invoice.primary_recipient.family_name	string	收件者的姓氏（即姓氏）。
電子郵件地址	invoice.primary_recipient.email_address	string	收件者的電子郵件地址。
電話號碼	invoice.primary_recipient.phone_number	string	收件者的電話號碼。
公用網址	invoice.public_url	string	Square 代管的帳單頁面的網址。使用 PublishInvoice 端點發佈發票後，Square 會託管發票頁面，並在回應中傳回頁面 URL。
Card	invoice.accepted_payment_methods.card	boolean	指出是否接受信用卡或簽帳金融卡付款。
Square 禮品卡	invoice.accepted_payment_methods.square_gift_card	boolean	指出是否接受 Square 禮品卡付款。
銀行帳戶	invoice.accepted_payment_methods.bank_account	boolean	指出是否接受銀行轉帳付款。
自訂欄位	invoice.custom_fields	array of object
標籤	invoice.custom_fields.label	string	自訂欄位的標籤或標題。
價值觀	invoice.custom_fields.value	string	自訂欄位的文字。
放置	invoice.custom_fields.placement	string	發票上自訂欄位的位置。
送貨方式	invoice.delivery_method	string	Square 用來向顧客傳送發票、提醒和收據的配送方式。發票發布後，Square 會根據交付方式和付款請求設置處理發票，可以立即處理發票，也可以在scheduled_at日期處理發票（如果指定）。
銷售或服務日期	invoice.sale_or_service_date	string	銷售日期或提供服務的日期，以 YYYY-MM-DD 格式。此欄位可用來指定發票上顯示的過去或未來日期。

目錄信息

作業識別碼：: CatalogInfo

擷取 Square Catalog API 的相關資訊，例如 BatchUpsertCatalogObjects 端點可以使用的批次大小限制。

傳回

名稱	路徑	類型	Description
批次更新插入每個批次的物件數上限	limits.batch_upsert_max_objects_per_batch	integer	/v2/catalog/batch-upsert 要求中單一批次內可能出現的物件數目上限。
批次更新插入物件總數上限	limits.batch_upsert_max_total_objects	integer	/v2/catalog/batch-upsert 要求中所有批次中可能出現的物件數目上限。
批次擷取最大物件識別碼	limits.batch_retrieve_max_object_ids	integer	/v2/catalog/batch-retrieve 要求中可能出現的物件 ID 數目上限。
搜尋最大頁面限制	limits.search_max_page_limit	integer	/v2/catalog/search回應頁面中可能傳回的結果數目上限。
批次刪除最大物件識別碼	limits.batch_delete_max_object_ids	integer	單一 /v2/catalog/batch-delete 要求中可能包含的物件 ID 數目上限。
更新項目稅項最大項目識別碼	limits.update_item_taxes_max_item_ids	integer	單一/v2/catalog/update-item-taxes請求中可包含的專案ID數目上限。
更新要啟用的項目稅金上限稅金	limits.update_item_taxes_max_taxes_to_enable	integer	單一/v2/catalog/update-item-taxes請求中可能包含的要啟用的稅號數目上限。
更新要停用的項目稅金上限	limits.update_item_taxes_max_taxes_to_disable	integer	單一/v2/catalog/update-item-taxes請求中可能包含的要停用的稅金ID數目上限。
更新項目修飾符列表最大項目 ID	limits.update_item_modifier_lists_max_item_ids	integer	單一/v2/catalog/update-item-taxes請求中可能包含的要停用的稅金ID數目上限。
更新物品修飾符清單要啟用的最大修飾符清單	limits.update_item_modifier_lists_max_modifier_lists_to_enable	integer	要啟用的修飾元清單ID數目上限，可包含在單一/v2/catalog/update-item-modifier-lists要求中。
更新物品修改器列表要禁用的最大修改器列表	limits.update_item_modifier_lists_max_modifier_lists_to_disable	integer	要停用的修飾元清單 ID 數目上限，可包含在單一 /v2/catalog/update-item-modifier-lists 要求中。

繼續訂閱

作業識別碼：: SubscriptionResume

繼續已停用的訂閱。

參數

名稱	機碼	必要	類型	Description
訂用帳戶識別碼	subscription_id	True	string	訂用帳戶的識別碼。

傳回

名稱	路徑	類型	Description
ID	subscription.id	string	Square 發行的唯一識別碼。
位置標識碼	subscription.location_id	string	位置的識別碼。
方案標識碼	subscription.plan_id	string	相關聯訂閱方案的識別碼。
客戶識別碼	subscription.customer_id	string	此物件代表客戶的 ID。
地位	subscription.status	string	此物件的目前驗證狀態。
總數	subscription.price_override_money.amount	integer	金額。
貨幣	subscription.price_override_money.currency	string	貨幣。
版本	subscription.version	integer	此物件的目前版本。
創建於	subscription.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
Timezone	subscription.timezone	string	用來解譯行事曆日期的時區。建立發票時，此欄位會設定為為賣方位置指定的時區。無法變更值。
名稱	subscription.source.name	string	名稱。

複製訂單（Beta）

作業識別碼：: OrderClone

透過複製現有訂單來建立處於 DRAFT 狀態的新訂單。新建立的訂單只有從原始訂單複製的核心欄位（例如明細項目、稅金和折扣）。

參數

名稱	機碼	類型	Description
訂單編號	order_id	string	訂單識別碼。
版本	version	integer	版本。
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。

傳回

名稱	路徑	類型	Description
ID	order.id	string	Square 發行的唯一識別碼。
位置標識碼	order.location_id	string	位置的識別碼。
明細項目	order.line_items	array of object
UID	order.line_items.uid	string	Square 產生的 ID。
名稱	order.line_items.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
數量	order.line_items.quantity	string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
適用稅項	order.line_items.applied_taxes	array of object
UID	order.line_items.applied_taxes.uid	string	Square 指派的 ID。
稅務 UID	order.line_items.applied_taxes.tax_uid	string	此套用稅金所代表之稅金的 UID。
總數	order.line_items.applied_taxes.applied_money.amount	integer	金額。
貨幣	order.line_items.applied_taxes.applied_money.currency	string	貨幣。
適用折扣	order.line_items.applied_discounts	array of object
UID	order.line_items.applied_discounts.uid	string	Square 指派的 ID。
折扣 UID	order.line_items.applied_discounts.discount_uid	string	套用折扣所代表的折扣 uid。
總數	order.line_items.applied_discounts.applied_money.amount	integer	金額。
貨幣	order.line_items.applied_discounts.applied_money.currency	string	貨幣。
總數	order.line_items.base_price_money.amount	integer	金額。
貨幣	order.line_items.base_price_money.currency	string	貨幣。
總數	order.line_items.gross_sales_money.amount	integer	金額。
貨幣	order.line_items.gross_sales_money.currency	string	貨幣。
總數	order.line_items.total_tax_money.amount	integer	金額。
貨幣	order.line_items.total_tax_money.currency	string	貨幣。
總數	order.line_items.total_discount_money.amount	integer	金額。
貨幣	order.line_items.total_discount_money.currency	string	貨幣。
總數	order.line_items.total_money.amount	integer	金額。
貨幣	order.line_items.total_money.currency	string	貨幣。
總數	order.line_items.variation_total_price_money.amount	integer	金額。
貨幣	order.line_items.variation_total_price_money.currency	string	貨幣。
目錄物件識別碼	order.line_items.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
變化名稱	order.line_items.variation_name	string	套用至此明細項目的變數名稱。
修飾詞	order.line_items.modifiers	array of object
UID	order.line_items.modifiers.uid	string	Square 指派的 ID。
目錄物件識別碼	order.line_items.modifiers.catalog_object_id	string	目錄物件 ID。
名稱	order.line_items.modifiers.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
總數	order.line_items.modifiers.base_price_money.amount	integer	金額。
貨幣	order.line_items.modifiers.base_price_money.currency	string	貨幣。
總數	order.line_items.modifiers.total_price_money.amount	integer	金額。
貨幣	order.line_items.modifiers.total_price_money.currency	string	貨幣。
稅款	order.taxes	array of object
UID	order.taxes.uid	string	Square 產生的 ID。
名稱	order.taxes.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
類型	order.taxes.type	string	指出類型。
百分比	order.taxes.percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
總數	order.taxes.applied_money.amount	integer	金額。
貨幣	order.taxes.applied_money.currency	string	貨幣。
Scope	order.taxes.scope	string	指出目前的層級。
折扣	order.discounts	array of object
UID	order.discounts.uid	string	Square 產生的 ID。
目錄物件識別碼	order.discounts.catalog_object_id	string	所追蹤之 CatalogObject 的 Square 產生識別碼。
名稱	order.discounts.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
類型	order.discounts.type	string	指出類型。
百分比	order.discounts.percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
總數	order.discounts.applied_money.amount	integer	金額。
貨幣	order.discounts.applied_money.currency	string	貨幣。
Scope	order.discounts.scope	string	指出目前的層級。
總數	order.discounts.amount_money.amount	integer	金額。
貨幣	order.discounts.amount_money.currency	string	貨幣。
創建於	order.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	order.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
State	order.state	string	目前的狀態。
版本	order.version	integer	此物件的目前版本。
參考標識碼	order.reference_id	string	選用的使用者定義參照 ID。
總數	order.total_money.amount	integer	金額。
貨幣	order.total_money.currency	string	貨幣。
總數	order.total_tax_money.amount	integer	金額。
貨幣	order.total_tax_money.currency	string	貨幣。
總數	order.total_discount_money.amount	integer	金額。
貨幣	order.total_discount_money.currency	string	貨幣。
總數	order.total_tip_money.amount	integer	金額。
貨幣	order.total_tip_money.currency	string	貨幣。
總數	order.total_service_charge_money.amount	integer	金額。
貨幣	order.total_service_charge_money.currency	string	貨幣。
總數	order.net_amounts.total_money.amount	integer	金額。
貨幣	order.net_amounts.total_money.currency	string	貨幣。
總數	order.net_amounts.tax_money.amount	integer	金額。
貨幣	order.net_amounts.tax_money.currency	string	貨幣。
總數	order.net_amounts.discount_money.amount	integer	金額。
貨幣	order.net_amounts.discount_money.currency	string	貨幣。
總數	order.net_amounts.tip_money.amount	integer	金額。
貨幣	order.net_amounts.tip_money.currency	string	貨幣。
總數	order.net_amounts.service_charge_money.amount	integer	金額。
貨幣	order.net_amounts.service_charge_money.currency	string	貨幣。
名稱	order.source.name	string	名稱。

計算訂單（Beta）

作業識別碼：: OrderCalculate

可讓應用程式預覽訂單定價，而無需建立訂單。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
位置標識碼	location_id	string	位置的識別碼。
名稱	name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
百分比	percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
Scope	scope	string	指出目前的層級。
名稱	name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
數量	quantity	string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
總數	amount	integer	金額。
貨幣	currency	string	貨幣。

傳回

名稱	路徑	類型	Description
位置標識碼	order.location_id	string	位置的識別碼。
明細項目	order.line_items	array of object
UID	order.line_items.uid	string	Square 產生的 ID。
數量	order.line_items.quantity	string	受實體計數影響的項目數，以十進位字串形式表示。該數字最多可以支持小數點後的 5 位數字。
名稱	order.line_items.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
總數	order.line_items.base_price_money.amount	integer	金額。
貨幣	order.line_items.base_price_money.currency	string	貨幣。
總數	order.line_items.gross_sales_money.amount	integer	金額。
貨幣	order.line_items.gross_sales_money.currency	string	貨幣。
總數	order.line_items.total_tax_money.amount	integer	金額。
貨幣	order.line_items.total_tax_money.currency	string	貨幣。
總數	order.line_items.total_discount_money.amount	integer	金額。
貨幣	order.line_items.total_discount_money.currency	string	貨幣。
總數	order.line_items.total_money.amount	integer	金額。
貨幣	order.line_items.total_money.currency	string	貨幣。
總數	order.line_items.variation_total_price_money.amount	integer	金額。
貨幣	order.line_items.variation_total_price_money.currency	string	貨幣。
適用折扣	order.line_items.applied_discounts	array of object
UID	order.line_items.applied_discounts.uid	string	Square 指派的 ID。
折扣 UID	order.line_items.applied_discounts.discount_uid	string	套用折扣所代表的折扣 uid。
總數	order.line_items.applied_discounts.applied_money.amount	integer	金額。
貨幣	order.line_items.applied_discounts.applied_money.currency	string	貨幣。
折扣	order.discounts	array of object
UID	order.discounts.uid	string	Square 產生的 ID。
名稱	order.discounts.name	string	項目的名稱。這是用於適用查詢過濾器的可搜尋屬性，其值不得為空，且長度為 Unicode 字碼點。
百分比	order.discounts.percentage	string	小數形式的百分比，使用「.」作為小數點分隔符，不帶「%」符號。值 7.5 對應於 7.5%。
總數	order.discounts.applied_money.amount	integer	金額。
貨幣	order.discounts.applied_money.currency	string	貨幣。
類型	order.discounts.type	string	指出類型。
Scope	order.discounts.scope	string	指出目前的層級。
創建於	order.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	order.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
State	order.state	string	目前的狀態。
版本	order.version	integer	此物件的目前版本。
總數	order.total_tax_money.amount	integer	金額。
貨幣	order.total_tax_money.currency	string	貨幣。
總數	order.total_discount_money.amount	integer	金額。
貨幣	order.total_discount_money.currency	string	貨幣。
總數	order.total_tip_money.amount	integer	金額。
貨幣	order.total_tip_money.currency	string	貨幣。
總數	order.total_money.amount	integer	金額。
貨幣	order.total_money.currency	string	貨幣。
總數	order.total_service_charge_money.amount	integer	金額。
貨幣	order.total_service_charge_money.currency	string	貨幣。
總數	order.net_amounts.total_money.amount	integer	金額。
貨幣	order.net_amounts.total_money.currency	string	貨幣。
總數	order.net_amounts.tax_money.amount	integer	金額。
貨幣	order.net_amounts.tax_money.currency	string	貨幣。
總數	order.net_amounts.discount_money.amount	integer	金額。
貨幣	order.net_amounts.discount_money.currency	string	貨幣。
總數	order.net_amounts.tip_money.amount	integer	金額。
貨幣	order.net_amounts.tip_money.currency	string	貨幣。
總數	order.net_amounts.service_charge_money.amount	integer	金額。
貨幣	order.net_amounts.service_charge_money.currency	string	貨幣。

註冊 Apple Pay 網域

作業識別碼：: ApplePayRegister

啟用網域以與 Apple Pay on the Web 和 Square 搭配使用。 Apple 會在此網域上執行驗證，以確保已正確設定為已啟用 Apple Pay 的網域。

參數

名稱	機碼	必要	類型	Description
網域名稱	domain_name	True	string	RFC-1034 中所述的網域名稱，將向 Apple Pay 註冊。

傳回

名稱	路徑	類型	Description
地位	status	string	網域註冊的狀態。

退款付款

作業識別碼：: RefundPayment

退款付款。您可以退還全部付款金額或部分付款金額。您可以使用此端點來退還卡片付款，或記錄現金或外部付款的退款。

參數

名稱	機碼	類型	Description
冪等金鑰	idempotency_key	string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。
付款標識碼	payment_id	string	要退款的付款的唯一 ID。
總數	amount	integer	接受這筆付款的金額，不包括tip_money。
貨幣	currency	string	3 個字元的 ISO 4217 貨幣代碼。
總數	amount	integer	接受這筆付款的金額，不包括tip_money。
貨幣	currency	string	3 個字元的 ISO 4217 貨幣代碼。
原因	reason	string	退款原因的說明。

傳回

名稱	路徑	類型	Description
ID	refund.id	string	Square 發行的唯一識別碼。
地位	refund.status	string	此物件的目前驗證狀態。
總數	refund.amount_money.amount	integer	金額。
貨幣	refund.amount_money.currency	string	貨幣。
付款標識碼	refund.payment_id	string	付款的唯一 ID。
訂單編號	refund.order_id	string	訂單的識別碼。
創建於	refund.created_at	string	指定此物件建立時間的時間戳記，採用 RFC 3339 格式。
更新於	refund.updated_at	string	指定此物件最近更新時間的時間戳記，採用 RFC 3339 格式。
總數	refund.app_fee_money.amount	integer	金額。
貨幣	refund.app_fee_money.currency	string	貨幣。
位置標識碼	refund.location_id	string	位置的識別碼。
原因	refund.reason	string	這個物件的原因。

透過冪等金鑰取消付款

作業識別碼：: PaymentCancelIdempotency

取消（作廢）請求中指定的冪等金鑰所識別的付款。當 CreatePayment 請求的狀態未知時，請使用此方法（例如，在您傳送 CreatePayment 請求之後，發生網路錯誤，而且您沒有收到回應）。在這種情況下，您可以指示 Square 使用此端點取消付款。在請求中，您提供與 CreatePayment 請求中要取消的相同冪等索引鍵。取消付款後，您可以再次提交 CreatePayment 請求。請注意，如果找不到具有指定冪等金鑰的付款，則不會採取任何動作，且端點會成功傳回。

參數

名稱	機碼	必要	類型	Description
冪等金鑰	idempotency_key		string	您指定的值，可在所有要求中唯一識別此要求。建立有效冪等索引鍵的常見方式是使用通用唯一識別碼（UUID）。

共用方式為

Square Payments （獨立發行商） （預覽版）