{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-create-gift-card-activity-request-schema.json", "title": "CreateGiftCardActivityRequest", "description": "A request to create a gift card activity.", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/square-giftcardactivities-api-openapi.yml#/components/schemas/CreateGiftCardActivityRequest", "type": "object", "x-release-status": "PUBLIC", "required": [ "idempotency_key", "gift_card_activity" ], "properties": { "idempotency_key": { "type": "string", "description": "A unique string that identifies the `CreateGiftCardActivity` request.", "minLength": 1, "maxLength": 128 }, "gift_card_activity": { "$ref": "#/$defs/GiftCardActivity", "description": "The activity to create for the gift card. This activity must specify `gift_card_id` or `gift_card_gan` for the target\ngift card, the `location_id` where the activity occurred, and the activity `type` along with the corresponding activity details." } }, "$defs": { "Currency": { "type": "string", "enum": [ "UNKNOWN_CURRENCY", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SLE", "SOS", "SRD", "SSP", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "USS", "UYI", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XTS", "XXX", "YER", "ZAR", "ZMK", "ZMW", "BTC", "XUS" ], "x-enum-elements": [ { "name": "UNKNOWN_CURRENCY", "description": "Unknown currency" }, { "name": "AED", "description": "United Arab Emirates dirham" }, { "name": "AFN", "description": "Afghan afghani" }, { "name": "ALL", "description": "Albanian lek" }, { "name": "AMD", "description": "Armenian dram" }, { "name": "ANG", "description": "Netherlands Antillean guilder" }, { "name": "AOA", "description": "Angolan kwanza" }, { "name": "ARS", "description": "Argentine peso" }, { "name": "AUD", "description": "Australian dollar" }, { "name": "AWG", "description": "Aruban florin" }, { "name": "AZN", "description": "Azerbaijani manat" }, { "name": "BAM", "description": "Bosnia and Herzegovina convertible mark" }, { "name": "BBD", "description": "Barbados dollar" }, { "name": "BDT", "description": "Bangladeshi taka" }, { "name": "BGN", "description": "Bulgarian lev" }, { "name": "BHD", "description": "Bahraini dinar" }, { "name": "BIF", "description": "Burundian franc" }, { "name": "BMD", "description": "Bermudian dollar" }, { "name": "BND", "description": "Brunei dollar" }, { "name": "BOB", "description": "Boliviano" }, { "name": "BOV", "description": "Bolivian Mvdol" }, { "name": "BRL", "description": "Brazilian real" }, { "name": "BSD", "description": "Bahamian dollar" }, { "name": "BTN", "description": "Bhutanese ngultrum" }, { "name": "BWP", "description": "Botswana pula" }, { "name": "BYR", "description": "Belarusian ruble" }, { "name": "BZD", "description": "Belize dollar" }, { "name": "CAD", "description": "Canadian dollar" }, { "name": "CDF", "description": "Congolese franc" }, { "name": "CHE", "description": "WIR Euro" }, { "name": "CHF", "description": "Swiss franc" }, { "name": "CHW", "description": "WIR Franc" }, { "name": "CLF", "description": "Unidad de Fomento" }, { "name": "CLP", "description": "Chilean peso" }, { "name": "CNY", "description": "Chinese yuan" }, { "name": "COP", "description": "Colombian peso" }, { "name": "COU", "description": "Unidad de Valor Real" }, { "name": "CRC", "description": "Costa Rican colon" }, { "name": "CUC", "description": "Cuban convertible peso" }, { "name": "CUP", "description": "Cuban peso" }, { "name": "CVE", "description": "Cape Verdean escudo" }, { "name": "CZK", "description": "Czech koruna" }, { "name": "DJF", "description": "Djiboutian franc" }, { "name": "DKK", "description": "Danish krone" }, { "name": "DOP", "description": "Dominican peso" }, { "name": "DZD", "description": "Algerian dinar" }, { "name": "EGP", "description": "Egyptian pound" }, { "name": "ERN", "description": "Eritrean nakfa" }, { "name": "ETB", "description": "Ethiopian birr" }, { "name": "EUR", "description": "Euro" }, { "name": "FJD", "description": "Fiji dollar" }, { "name": "FKP", "description": "Falkland Islands pound" }, { "name": "GBP", "description": "Pound sterling" }, { "name": "GEL", "description": "Georgian lari" }, { "name": "GHS", "description": "Ghanaian cedi" }, { "name": "GIP", "description": "Gibraltar pound" }, { "name": "GMD", "description": "Gambian dalasi" }, { "name": "GNF", "description": "Guinean franc" }, { "name": "GTQ", "description": "Guatemalan quetzal" }, { "name": "GYD", "description": "Guyanese dollar" }, { "name": "HKD", "description": "Hong Kong dollar" }, { "name": "HNL", "description": "Honduran lempira" }, { "name": "HRK", "description": "Croatian kuna" }, { "name": "HTG", "description": "Haitian gourde" }, { "name": "HUF", "description": "Hungarian forint" }, { "name": "IDR", "description": "Indonesian rupiah" }, { "name": "ILS", "description": "Israeli new shekel" }, { "name": "INR", "description": "Indian rupee" }, { "name": "IQD", "description": "Iraqi dinar" }, { "name": "IRR", "description": "Iranian rial" }, { "name": "ISK", "description": "Icelandic króna" }, { "name": "JMD", "description": "Jamaican dollar" }, { "name": "JOD", "description": "Jordanian dinar" }, { "name": "JPY", "description": "Japanese yen" }, { "name": "KES", "description": "Kenyan shilling" }, { "name": "KGS", "description": "Kyrgyzstani som" }, { "name": "KHR", "description": "Cambodian riel" }, { "name": "KMF", "description": "Comoro franc" }, { "name": "KPW", "description": "North Korean won" }, { "name": "KRW", "description": "South Korean won" }, { "name": "KWD", "description": "Kuwaiti dinar" }, { "name": "KYD", "description": "Cayman Islands dollar" }, { "name": "KZT", "description": "Kazakhstani tenge" }, { "name": "LAK", "description": "Lao kip" }, { "name": "LBP", "description": "Lebanese pound" }, { "name": "LKR", "description": "Sri Lankan rupee" }, { "name": "LRD", "description": "Liberian dollar" }, { "name": "LSL", "description": "Lesotho loti" }, { "name": "LTL", "description": "Lithuanian litas" }, { "name": "LVL", "description": "Latvian lats" }, { "name": "LYD", "description": "Libyan dinar" }, { "name": "MAD", "description": "Moroccan dirham" }, { "name": "MDL", "description": "Moldovan leu" }, { "name": "MGA", "description": "Malagasy ariary" }, { "name": "MKD", "description": "Macedonian denar" }, { "name": "MMK", "description": "Myanmar kyat" }, { "name": "MNT", "description": "Mongolian tögrög" }, { "name": "MOP", "description": "Macanese pataca" }, { "name": "MRO", "description": "Mauritanian ouguiya" }, { "name": "MUR", "description": "Mauritian rupee" }, { "name": "MVR", "description": "Maldivian rufiyaa" }, { "name": "MWK", "description": "Malawian kwacha" }, { "name": "MXN", "description": "Mexican peso" }, { "name": "MXV", "description": "Mexican Unidad de Inversion" }, { "name": "MYR", "description": "Malaysian ringgit" }, { "name": "MZN", "description": "Mozambican metical" }, { "name": "NAD", "description": "Namibian dollar" }, { "name": "NGN", "description": "Nigerian naira" }, { "name": "NIO", "description": "Nicaraguan córdoba" }, { "name": "NOK", "description": "Norwegian krone" }, { "name": "NPR", "description": "Nepalese rupee" }, { "name": "NZD", "description": "New Zealand dollar" }, { "name": "OMR", "description": "Omani rial" }, { "name": "PAB", "description": "Panamanian balboa" }, { "name": "PEN", "description": "Peruvian sol" }, { "name": "PGK", "description": "Papua New Guinean kina" }, { "name": "PHP", "description": "Philippine peso" }, { "name": "PKR", "description": "Pakistani rupee" }, { "name": "PLN", "description": "Polish zBoty" }, { "name": "PYG", "description": "Paraguayan guaraní" }, { "name": "QAR", "description": "Qatari riyal" }, { "name": "RON", "description": "Romanian leu" }, { "name": "RSD", "description": "Serbian dinar" }, { "name": "RUB", "description": "Russian ruble" }, { "name": "RWF", "description": "Rwandan franc" }, { "name": "SAR", "description": "Saudi riyal" }, { "name": "SBD", "description": "Solomon Islands dollar" }, { "name": "SCR", "description": "Seychelles rupee" }, { "name": "SDG", "description": "Sudanese pound" }, { "name": "SEK", "description": "Swedish krona" }, { "name": "SGD", "description": "Singapore dollar" }, { "name": "SHP", "description": "Saint Helena pound" }, { "name": "SLL", "description": "Sierra Leonean first leone" }, { "name": "SLE", "description": "Sierra Leonean second leone" }, { "name": "SOS", "description": "Somali shilling" }, { "name": "SRD", "description": "Surinamese dollar" }, { "name": "SSP", "description": "South Sudanese pound" }, { "name": "STD", "description": "São Tomé and Príncipe dobra" }, { "name": "SVC", "description": "Salvadoran colón" }, { "name": "SYP", "description": "Syrian pound" }, { "name": "SZL", "description": "Swazi lilangeni" }, { "name": "THB", "description": "Thai baht" }, { "name": "TJS", "description": "Tajikstani somoni" }, { "name": "TMT", "description": "Turkmenistan manat" }, { "name": "TND", "description": "Tunisian dinar" }, { "name": "TOP", "description": "Tongan pa'anga" }, { "name": "TRY", "description": "Turkish lira" }, { "name": "TTD", "description": "Trinidad and Tobago dollar" }, { "name": "TWD", "description": "New Taiwan dollar" }, { "name": "TZS", "description": "Tanzanian shilling" }, { "name": "UAH", "description": "Ukrainian hryvnia" }, { "name": "UGX", "description": "Ugandan shilling" }, { "name": "USD", "description": "United States dollar" }, { "name": "USN", "description": "United States dollar (next day)" }, { "name": "USS", "description": "United States dollar (same day)" }, { "name": "UYI", "description": "Uruguay Peso en Unidedades Indexadas" }, { "name": "UYU", "description": "Uruguyan peso" }, { "name": "UZS", "description": "Uzbekistan som" }, { "name": "VEF", "description": "Venezuelan bolívar soberano" }, { "name": "VND", "description": "Vietnamese ’Óng" }, { "name": "VUV", "description": "Vanuatu vatu" }, { "name": "WST", "description": "Samoan tala" }, { "name": "XAF", "description": "CFA franc BEAC" }, { "name": "XAG", "description": "Silver" }, { "name": "XAU", "description": "Gold" }, { "name": "XBA", "description": "European Composite Unit" }, { "name": "XBB", "description": "European Monetary Unit" }, { "name": "XBC", "description": "European Unit of Account 9" }, { "name": "XBD", "description": "European Unit of Account 17" }, { "name": "XCD", "description": "East Caribbean dollar" }, { "name": "XDR", "description": "Special drawing rights (International Monetary Fund)" }, { "name": "XOF", "description": "CFA franc BCEAO" }, { "name": "XPD", "description": "Palladium" }, { "name": "XPF", "description": "CFP franc" }, { "name": "XPT", "description": "Platinum" }, { "name": "XTS", "description": "Code reserved for testing" }, { "name": "XXX", "description": "No currency" }, { "name": "YER", "description": "Yemeni rial" }, { "name": "ZAR", "description": "South African rand" }, { "name": "ZMK", "description": "Zambian kwacha" }, { "name": "ZMW", "description": "Zambian kwacha" }, { "name": "BTC", "description": "Bitcoin" }, { "name": "XUS", "description": "USD Coin" } ], "description": "Indicates the associated currency for an amount of money. Values correspond\nto [ISO 4217](https://wikipedia.org/wiki/ISO_4217).", "x-release-status": "PUBLIC" }, "GiftCardActivity": { "type": "object", "description": "Represents an action performed on a [gift card](entity:GiftCard) that affects its state or balance. \nA gift card activity contains information about a specific activity type. For example, a `REDEEM` activity\nincludes a `redeem_activity_details` field that contains information about the redemption.", "x-release-status": "PUBLIC", "required": [ "type", "location_id" ], "properties": { "id": { "type": "string", "description": "The Square-assigned ID of the gift card activity.", "readOnly": true }, "type": { "$ref": "#/$defs/GiftCardActivityType", "description": "The type of gift card activity.\nSee [Type](#type-type) for possible values" }, "location_id": { "type": "string", "description": "The ID of the [business location](entity:Location) where the activity occurred." }, "created_at": { "type": "string", "description": "The timestamp when the gift card activity was created, in RFC 3339 format.", "readOnly": true }, "gift_card_id": { "type": [ "string", "null" ], "description": "The gift card ID. When creating a gift card activity, `gift_card_id` is not required if \n`gift_card_gan` is specified." }, "gift_card_gan": { "type": [ "string", "null" ], "description": "The gift card account number (GAN). When creating a gift card activity, `gift_card_gan` \nis not required if `gift_card_id` is specified." }, "gift_card_balance_money": { "$ref": "#/$defs/Money", "description": "The final balance on the gift card after the action is completed.", "readOnly": true }, "load_activity_details": { "$ref": "#/$defs/GiftCardActivityLoad", "description": "Additional details about a `LOAD` activity, which is used to reload money onto a gift card." }, "activate_activity_details": { "$ref": "#/$defs/GiftCardActivityActivate", "description": "Additional details about an `ACTIVATE` activity, which is used to activate a gift card with \nan initial balance." }, "redeem_activity_details": { "$ref": "#/$defs/GiftCardActivityRedeem", "description": "Additional details about a `REDEEM` activity, which is used to redeem a gift card for a purchase.\n\nFor applications that process payments using the Square Payments API, Square creates a `REDEEM` activity that \nupdates the gift card balance after the corresponding [CreatePayment](api-endpoint:Payments-CreatePayment) \nrequest is completed. Applications that use a custom payment processing system must call \n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) to create the `REDEEM` activity." }, "clear_balance_activity_details": { "$ref": "#/$defs/GiftCardActivityClearBalance", "description": "Additional details about a `CLEAR_BALANCE` activity, which is used to set the balance of a gift card to zero." }, "deactivate_activity_details": { "$ref": "#/$defs/GiftCardActivityDeactivate", "description": "Additional details about a `DEACTIVATE` activity, which is used to deactivate a gift card." }, "adjust_increment_activity_details": { "$ref": "#/$defs/GiftCardActivityAdjustIncrement", "description": "Additional details about an `ADJUST_INCREMENT` activity, which is used to add money to a gift card \noutside of a typical `ACTIVATE`, `LOAD`, or `REFUND` activity flow." }, "adjust_decrement_activity_details": { "$ref": "#/$defs/GiftCardActivityAdjustDecrement", "description": "Additional details about an `ADJUST_DECREMENT` activity, which is used to deduct money from a gift \ncard outside of a typical `REDEEM` activity flow." }, "refund_activity_details": { "$ref": "#/$defs/GiftCardActivityRefund", "description": "Additional details about a `REFUND` activity, which is used to add money to a gift card when \nrefunding a payment.\n\nFor applications that refund payments to a gift card using the Square Refunds API, Square automatically\ncreates a `REFUND` activity that updates the gift card balance after a [RefundPayment](api-endpoint:Refunds-RefundPayment)\nrequest is completed. Applications that use a custom processing system must call\n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) to create the `REFUND` activity." }, "unlinked_activity_refund_activity_details": { "$ref": "#/$defs/GiftCardActivityUnlinkedActivityRefund", "description": "Additional details about an `UNLINKED_ACTIVITY_REFUND` activity. This activity is used to add money \nto a gift card when refunding a payment that was processed using a custom payment processing system\nand not linked to the gift card." }, "import_activity_details": { "$ref": "#/$defs/GiftCardActivityImport", "description": "Additional details about an `IMPORT` activity, which Square uses to import a third-party \ngift card with a balance.", "readOnly": true }, "block_activity_details": { "$ref": "#/$defs/GiftCardActivityBlock", "description": "Additional details about a `BLOCK` activity, which Square uses to temporarily block a gift card.", "readOnly": true }, "unblock_activity_details": { "$ref": "#/$defs/GiftCardActivityUnblock", "description": "Additional details about an `UNBLOCK` activity, which Square uses to unblock a gift card.", "readOnly": true }, "import_reversal_activity_details": { "$ref": "#/$defs/GiftCardActivityImportReversal", "description": "Additional details about an `IMPORT_REVERSAL` activity, which Square uses to reverse the \nimport of a third-party gift card.", "readOnly": true }, "transfer_balance_to_activity_details": { "$ref": "#/$defs/GiftCardActivityTransferBalanceTo", "description": "Additional details about a `TRANSFER_BALANCE_TO` activity, which Square uses to add money to\na gift card as the result of a transfer from another gift card.", "readOnly": true }, "transfer_balance_from_activity_details": { "$ref": "#/$defs/GiftCardActivityTransferBalanceFrom", "description": "Additional details about a `TRANSFER_BALANCE_FROM` activity, which Square uses to deduct money from\na gift as the result of a transfer to another gift card.", "readOnly": true } } }, "GiftCardActivityActivate": { "type": "object", "description": "Represents details about an `ACTIVATE` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "properties": { "amount_money": { "$ref": "#/$defs/Money", "description": "The amount added to the gift card. This value is a positive integer.\n\nApplications that use a custom order processing system must specify this amount in the \n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request." }, "order_id": { "type": [ "string", "null" ], "description": "The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.\n\nApplications that use the Square Orders API to process orders must specify the order ID\n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request." }, "line_item_uid": { "type": [ "string", "null" ], "description": "The UID of the `GIFT_CARD` line item in the order that represents the gift card purchase.\n\nApplications that use the Square Orders API to process orders must specify the line item UID\nin the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request." }, "reference_id": { "type": [ "string", "null" ], "description": "A client-specified ID that associates the gift card activity with an entity in another system. \n\nApplications that use a custom order processing system can use this field to track information \nrelated to an order or payment." }, "buyer_payment_instrument_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The payment instrument IDs used to process the gift card purchase, such as a credit card ID \nor bank account ID. \n\nApplications that use a custom order processing system must specify payment instrument IDs in \nthe [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.\nSquare uses this information to perform compliance checks. \n\nFor applications that use the Square Orders API to process payments, Square has the necessary \ninstrument IDs to perform compliance checks.\n\nEach buyer payment instrument ID can contain a maximum of 255 characters." } } }, "GiftCardActivityAdjustDecrement": { "type": "object", "description": "Represents details about an `ADJUST_DECREMENT` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "amount_money", "reason" ], "properties": { "amount_money": { "$ref": "#/$defs/Money", "description": "The amount deducted from the gift card balance. This value is a positive integer." }, "reason": { "$ref": "#/$defs/GiftCardActivityAdjustDecrementReason", "description": "The reason the gift card balance was adjusted.\nSee [Reason](#type-reason) for possible values" } } }, "GiftCardActivityAdjustDecrementReason": { "type": "string", "enum": [ "SUSPICIOUS_ACTIVITY", "BALANCE_ACCIDENTALLY_INCREASED", "SUPPORT_ISSUE", "PURCHASE_WAS_REFUNDED" ], "x-enum-elements": [ { "name": "SUSPICIOUS_ACTIVITY", "description": "The balance was decreased because the seller detected suspicious or fraudulent activity\non the gift card." }, { "name": "BALANCE_ACCIDENTALLY_INCREASED", "description": "The balance was decreased to reverse an unintentional balance increase." }, { "name": "SUPPORT_ISSUE", "description": "The balance was decreased to accommodate support issues." }, { "name": "PURCHASE_WAS_REFUNDED", "description": "The balance was decreased because the order used to purchase or reload the\ngift card was refunded." } ], "description": "Indicates the reason for deducting money from a [gift card](entity:GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityAdjustIncrement": { "type": "object", "description": "Represents details about an `ADJUST_INCREMENT` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "amount_money", "reason" ], "properties": { "amount_money": { "$ref": "#/$defs/Money", "description": "The amount added to the gift card balance. This value is a positive integer." }, "reason": { "$ref": "#/$defs/GiftCardActivityAdjustIncrementReason", "description": "The reason the gift card balance was adjusted.\nSee [Reason](#type-reason) for possible values" } } }, "GiftCardActivityAdjustIncrementReason": { "type": "string", "enum": [ "COMPLIMENTARY", "SUPPORT_ISSUE", "TRANSACTION_VOIDED" ], "x-enum-elements": [ { "name": "COMPLIMENTARY", "description": "The seller gifted a complimentary gift card balance increase." }, { "name": "SUPPORT_ISSUE", "description": "The seller increased the gift card balance \nto accommodate support issues." }, { "name": "TRANSACTION_VOIDED", "description": "The transaction is voided." } ], "description": "Indicates the reason for adding money to a [gift card](entity:GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityBlock": { "type": "object", "description": "Represents details about a `BLOCK` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "reason" ], "properties": { "reason": { "$ref": "#/$defs/GiftCardActivityBlockReason", "description": "The reason the gift card was blocked.\nSee [Reason](#type-reason) for possible values" } } }, "GiftCardActivityBlockReason": { "type": "string", "enum": [ "CHARGEBACK_BLOCK" ], "x-enum-elements": [ { "name": "CHARGEBACK_BLOCK", "description": "The gift card is blocked because the buyer initiated a chargeback on the gift card purchase." } ], "description": "Indicates the reason for blocking a [gift card](entity:GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityClearBalance": { "type": "object", "description": "Represents details about a `CLEAR_BALANCE` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "reason" ], "properties": { "reason": { "$ref": "#/$defs/GiftCardActivityClearBalanceReason", "description": "The reason the gift card balance was cleared.\nSee [Reason](#type-reason) for possible values" } } }, "GiftCardActivityClearBalanceReason": { "type": "string", "enum": [ "SUSPICIOUS_ACTIVITY", "REUSE_GIFTCARD", "UNKNOWN_REASON" ], "x-enum-elements": [ { "name": "SUSPICIOUS_ACTIVITY", "description": "The seller suspects suspicious activity." }, { "name": "REUSE_GIFTCARD", "description": "The seller cleared the balance to reuse the gift card." }, { "name": "UNKNOWN_REASON", "description": "The gift card balance was cleared for an unknown reason.\n\nThis reason is read-only and cannot be used to create a `CLEAR_BALANCE` activity using the Gift Card Activities API." } ], "description": "Indicates the reason for clearing the balance of a [gift card](entity:GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityDeactivate": { "type": "object", "description": "Represents details about a `DEACTIVATE` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "reason" ], "properties": { "reason": { "$ref": "#/$defs/GiftCardActivityDeactivateReason", "description": "The reason the gift card was deactivated.\nSee [Reason](#type-reason) for possible values" } } }, "GiftCardActivityDeactivateReason": { "type": "string", "enum": [ "SUSPICIOUS_ACTIVITY", "UNKNOWN_REASON", "CHARGEBACK_DEACTIVATE" ], "x-enum-elements": [ { "name": "SUSPICIOUS_ACTIVITY", "description": "The seller suspects suspicious activity." }, { "name": "UNKNOWN_REASON", "description": "The gift card was deactivated for an unknown reason.\n\nThis reason is read-only and cannot be used to create a `DEACTIVATE` activity using the Gift Card Activities API." }, { "name": "CHARGEBACK_DEACTIVATE", "description": "A chargeback on the gift card purchase (or the gift card load) was ruled in favor of the buyer.\n\nThis reason is read-only and cannot be used to create a `DEACTIVATE` activity using the Gift Card Activities API." } ], "description": "Indicates the reason for deactivating a [gift card](entity:GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityImport": { "type": "object", "description": "Represents details about an `IMPORT` [gift card activity type](entity:GiftCardActivityType).\nThis activity type is used when Square imports a third-party gift card, in which case the \n`gan_source` of the gift card is set to `OTHER`.", "x-release-status": "PUBLIC", "required": [ "amount_money" ], "properties": { "amount_money": { "$ref": "#/$defs/Money", "description": "The balance amount on the imported gift card." } } }, "GiftCardActivityImportReversal": { "type": "object", "description": "Represents details about an `IMPORT_REVERSAL` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "amount_money" ], "properties": { "amount_money": { "$ref": "#/$defs/Money", "description": "The amount of money cleared from the third-party gift card when \nthe import was reversed." } } }, "GiftCardActivityLoad": { "type": "object", "description": "Represents details about a `LOAD` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "properties": { "amount_money": { "$ref": "#/$defs/Money", "description": "The amount added to the gift card. This value is a positive integer.\n\nApplications that use a custom order processing system must specify this amount in the \n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request." }, "order_id": { "type": [ "string", "null" ], "description": "The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.\n\nApplications that use the Square Orders API to process orders must specify the order ID in the \n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request." }, "line_item_uid": { "type": [ "string", "null" ], "description": "The UID of the `GIFT_CARD` line item in the order that represents the additional funds for the gift card.\n\nApplications that use the Square Orders API to process orders must specify the line item UID\nin the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request." }, "reference_id": { "type": [ "string", "null" ], "description": "A client-specified ID that associates the gift card activity with an entity in another system. \n\nApplications that use a custom order processing system can use this field to track information related to \nan order or payment." }, "buyer_payment_instrument_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The payment instrument IDs used to process the order for the additional funds, such as a credit card ID \nor bank account ID. \n\nApplications that use a custom order processing system must specify payment instrument IDs in \nthe [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.\nSquare uses this information to perform compliance checks. \n\nFor applications that use the Square Orders API to process payments, Square has the necessary \ninstrument IDs to perform compliance checks.\n\nEach buyer payment instrument ID can contain a maximum of 255 characters." } } }, "GiftCardActivityRedeem": { "type": "object", "description": "Represents details about a `REDEEM` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "amount_money" ], "properties": { "amount_money": { "$ref": "#/$defs/Money", "description": "The amount deducted from the gift card for the redemption. This value is a positive integer.\n\nApplications that use a custom payment processing system must specify this amount in the \n[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request." }, "payment_id": { "type": "string", "description": "The ID of the payment that represents the gift card redemption. Square populates this field \nif the payment was processed by Square.", "readOnly": true }, "reference_id": { "type": [ "string", "null" ], "description": "A client-specified ID that associates the gift card activity with an entity in another system. \n\nApplications that use a custom payment processing system can use this field to track information\nrelated to an order or payment." }, "status": { "$ref": "#/$defs/GiftCardActivityRedeemStatus", "description": "The status of the gift card redemption. Gift cards redeemed from Square Point of Sale or the \nSquare Seller Dashboard use a two-state process: `PENDING` \nto `COMPLETED` or `PENDING` to `CANCELED`. Gift cards redeemed using the Gift Card Activities API \nalways have a `COMPLETED` status.\nSee [Status](#type-status) for possible values", "readOnly": true } } }, "GiftCardActivityRedeemStatus": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELED" ], "x-enum-elements": [ { "name": "PENDING", "description": "The gift card redemption is pending. `PENDING` is a temporary status that applies when a \ngift card is redeemed from Square Point of Sale or another Square product. A `PENDING` status is updated to \n`COMPLETED` if the payment is captured or `CANCELED` if the authorization is voided." }, { "name": "COMPLETED", "description": "The gift card redemption is completed." }, { "name": "CANCELED", "description": "The gift card redemption is canceled. A redemption is canceled if the authorization \non the gift card is voided." } ], "description": "Indicates the status of a [gift card](entity:GiftCard) redemption. This status is relevant only for\nredemptions made from Square products (such as Square Point of Sale) because Square products use a \ntwo-state process. Gift cards redeemed using the Gift Card Activities API always have a `COMPLETED` status.", "x-release-status": "PUBLIC" }, "GiftCardActivityRefund": { "type": "object", "description": "Represents details about a `REFUND` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "properties": { "redeem_activity_id": { "type": [ "string", "null" ], "description": "The ID of the refunded `REDEEM` gift card activity. Square populates this field if the \n`payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request \nrepresents a gift card redemption.\n\nFor applications that use a custom payment processing system, this field is required when creating\na `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card." }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount added to the gift card for the refund. This value is a positive integer.\n\nThis field is required when creating a `REFUND` activity. The amount can represent a full or partial refund." }, "reference_id": { "type": [ "string", "null" ], "description": "A client-specified ID that associates the gift card activity with an entity in another system." }, "payment_id": { "type": "string", "description": "The ID of the refunded payment. Square populates this field if the refund is for a \npayment processed by Square. This field matches the `payment_id` in the corresponding\n[RefundPayment](api-endpoint:Refunds-RefundPayment) request.", "readOnly": true } } }, "GiftCardActivityTransferBalanceFrom": { "type": "object", "description": "Represents details about a `TRANSFER_BALANCE_FROM` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "transfer_to_gift_card_id", "amount_money" ], "properties": { "transfer_to_gift_card_id": { "type": "string", "description": "The ID of the gift card to which the specified amount was transferred." }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount deducted from the gift card for the transfer. This value is a positive integer." } } }, "GiftCardActivityTransferBalanceTo": { "type": "object", "description": "Represents details about a `TRANSFER_BALANCE_TO` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "transfer_from_gift_card_id", "amount_money" ], "properties": { "transfer_from_gift_card_id": { "type": "string", "description": "The ID of the gift card from which the specified amount was transferred." }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount added to the gift card balance for the transfer. This value is a positive integer." } } }, "GiftCardActivityType": { "type": "string", "enum": [ "ACTIVATE", "LOAD", "REDEEM", "CLEAR_BALANCE", "DEACTIVATE", "ADJUST_INCREMENT", "ADJUST_DECREMENT", "REFUND", "UNLINKED_ACTIVITY_REFUND", "IMPORT", "BLOCK", "UNBLOCK", "IMPORT_REVERSAL", "TRANSFER_BALANCE_FROM", "TRANSFER_BALANCE_TO" ], "x-enum-elements": [ { "name": "ACTIVATE", "description": "Activated a gift card with a balance. When a gift card is activated, Square changes \nthe gift card state from `PENDING` to `ACTIVE`. A gift card must be in the `ACTIVE` state \nto be used for other balance-changing activities." }, { "name": "LOAD", "description": "Loaded a gift card with additional funds." }, { "name": "REDEEM", "description": "Redeemed a gift card for a purchase." }, { "name": "CLEAR_BALANCE", "description": "Set the balance of a gift card to zero." }, { "name": "DEACTIVATE", "description": "Permanently blocked a gift card from balance-changing activities." }, { "name": "ADJUST_INCREMENT", "description": "Added money to a gift card outside of a typical `ACTIVATE`, `LOAD`, or `REFUND` activity flow." }, { "name": "ADJUST_DECREMENT", "description": "Deducted money from a gift card outside of a typical `REDEEM` activity flow." }, { "name": "REFUND", "description": "Added money to a gift card from a refunded transaction. A `REFUND` activity might be linked to \na Square payment, depending on how the payment and refund are processed. For example:\n- A payment processed by Square can be refunded to a `PENDING` or `ACTIVE` gift card using the Square\nSeller Dashboard, Square Point of Sale, or Refunds API.\n- A payment processed using a custom processing system can be refunded to the same gift card." }, { "name": "UNLINKED_ACTIVITY_REFUND", "description": "Added money to a gift card from a refunded transaction that was processed using a custom payment\nprocessing system and not linked to the gift card." }, { "name": "IMPORT", "description": "Imported a third-party gift card with a balance. `IMPORT` activities are managed \nby Square and cannot be created using the Gift Card Activities API." }, { "name": "BLOCK", "description": "Temporarily blocked a gift card from balance-changing activities. `BLOCK` activities \nare managed by Square and cannot be created using the Gift Card Activities API." }, { "name": "UNBLOCK", "description": "Unblocked a gift card, which enables it to resume balance-changing activities. `UNBLOCK` \nactivities are managed by Square and cannot be created using the Gift Card Activities API." }, { "name": "IMPORT_REVERSAL", "description": "Reversed the import of a third-party gift card, which sets the gift card state to \n`PENDING` and clears the balance. `IMPORT_REVERSAL` activities are managed by Square and \ncannot be created using the Gift Card Activities API." }, { "name": "TRANSFER_BALANCE_FROM", "description": "Deducted money from a gift card as the result of a transfer to the balance of another gift card.\n`TRANSFER_BALANCE_FROM` activities are managed by Square and cannot be created using the Gift Card Activities API." }, { "name": "TRANSFER_BALANCE_TO", "description": "Added money to a gift card as the result of a transfer from the balance of another gift card.\n`TRANSFER_BALANCE_TO` activities are managed by Square and cannot be created using the Gift Card Activities API." } ], "description": "Indicates the type of [gift card activity](entity:GiftCardActivity).", "x-release-status": "PUBLIC" }, "GiftCardActivityUnblock": { "type": "object", "description": "Represents details about an `UNBLOCK` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "reason" ], "properties": { "reason": { "$ref": "#/$defs/GiftCardActivityUnblockReason", "description": "The reason the gift card was unblocked.\nSee [Reason](#type-reason) for possible values" } } }, "GiftCardActivityUnblockReason": { "type": "string", "enum": [ "CHARGEBACK_UNBLOCK" ], "x-enum-elements": [ { "name": "CHARGEBACK_UNBLOCK", "description": "The gift card is unblocked because a chargeback was ruled in favor of the seller." } ], "description": "Indicates the reason for unblocking a [gift card](entity:GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityUnlinkedActivityRefund": { "type": "object", "description": "Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity type](entity:GiftCardActivityType).", "x-release-status": "PUBLIC", "required": [ "amount_money" ], "properties": { "amount_money": { "$ref": "#/$defs/Money", "description": "The amount added to the gift card for the refund. This value is a positive integer." }, "reference_id": { "type": [ "string", "null" ], "description": "A client-specified ID that associates the gift card activity with an entity in another system." }, "payment_id": { "type": "string", "description": "The ID of the refunded payment. This field is not used starting in Square version 2022-06-16.", "readOnly": true } } }, "Money": { "type": "object", "description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.", "x-release-status": "PUBLIC", "properties": { "amount": { "type": [ "integer", "null" ], "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "format": "int64" }, "currency": { "$ref": "#/$defs/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](entity:Currency) for possible values.\nSee [Currency](#type-currency) for possible values" } } } } }