--- updatedAt: 2026-05-27T07:59:25.000Z agentTools: siteIndex: https://developer.eagleeye.com/llms.txt projectIndex: https://developer.eagleeye.com/eagleeye-developer/llms.txt --- # Refund This API endpoint allows the calling application to record within AIR a refund (return) transaction. Request attribute `basket` should contain only a list of returned items (please note each returned item should have the attribute `salesKey=REFUND`), allowing AIR to update the original transaction. If one or more returned items had triggered an offer redemption, then AIR will unredeem appropriate COUPON(s) and depending on a Campaign setting (`unredeemable`) will put them back into the Consumer Wallet or Cancel them. Likewise, if loyalty points were earned in the original transaction, then depending on Scheme configuration (`isRefundable`) AIR will debit the difference arisen from the basket differences. Please note `location` provided to this endpoint will only be used to record where this refund happened (in which Store or Outlet); Settle's transaction location will be used for basket re-analysis, if applicable. # OpenAPI definition ```json { "x-explorer-enabled": false, "openapi": "3.0.3", "servers": [ { "url": "https://pos.uk.eagleeye.com/2.0", "description": "UK Production" } ], "info": { "version": "1.76.0", "title": "POS-Connect API", "description": "# AIR POS API\n\nSet of RESTFul API endpoints allowing Clients to integrate their physical or virtual Points of Sales (POS) into AIR platform.\n\nPlease note: Client Settings, agreed during each Client onboarding (and documented in their Config Document) could affect things and behaviours detailed there.\nFor example list of returned accounts for Open Wallet endpoint, could be automatically filtered-out to narrow down the amount of returned accounts. Also some of the entities sub-attributes could be ignored/hidden to reduce verbosity and to save bandwidth.\n\nList of the entity's attributes that could be \"hidden\"/ignored consist of:\n * walletEntity->meta\n * walletEntity->relationships\n * walletIdentity->meta\n * accountEntity->meta\n * accountEntity->relationships\n * walletConsumer->meta\n * walletIdentity->meta\n * fundEntity->meta\n\nPlease note:\n\n* Above mechanism will not change nor unset any data stored in the AIR Database(s). Instead, appropriate attributes will be ignored while constructing and sending a response to the calling application. Please refer to your Config Documentation for details.\n* The authentication mechanic requires the receipt of the full payload so any headers that would chunk the request up, such as transfer-encoding: chunked could potentially cause authentication failures.\n" }, "tags": [ { "name": "Wallet", "description": "API endpoints exposed in this section provide a high-level AIR functionality, based on most common Client's use cases. These high-level endpoints combine low-level functionality and reduce the amount of API calls needed." } ], "paths": { "/connect/wallet/refund": { "post": { "summary": "Refund", "operationId": "refundWalletTransaction", "tags": [ "Wallet" ], "description": "This API endpoint allows the calling application to record within AIR a refund (return) transaction. Request attribute `basket` should contain only a list of returned items (please note each returned item should have the attribute `salesKey=REFUND`), allowing AIR to update the original transaction. If one or more returned items had triggered an offer redemption, then AIR will unredeem appropriate COUPON(s) and depending on a Campaign setting (`unredeemable`) will put them back into the Consumer Wallet or Cancel them. Likewise, if loyalty points were earned in the original transaction, then depending on Scheme configuration (`isRefundable`) AIR will debit the difference arisen from the basket differences.\n Please note `location` provided to this endpoint will only be used to record where this refund happened (in which Store or Outlet); Settle's transaction location will be used for basket re-analysis, if applicable.", "requestBody": { "$ref": "#/components/requestBodies/refundPayload" }, "parameters": [ { "$ref": "#/components/parameters/httpAcceptEncodingRequest" }, { "$ref": "#/components/parameters/httpConnectionRequest" }, { "$ref": "#/components/parameters/httpContentTypeRequest" }, { "$ref": "#/components/parameters/eesAuthenticationClientId" }, { "$ref": "#/components/parameters/eesAuthenticationRequestHash" }, { "$ref": "#/components/parameters/eesMessageId" }, { "$ref": "#/components/parameters/customSubsystemId" }, { "$ref": "#/components/parameters/customWildCard" }, { "$ref": "#/components/parameters/httpMethodOverride" }, { "$ref": "#/components/parameters/eesDateTimeOverride" } ], "responses": { "200": { "$ref": "#/components/responses/200refundResponsePayload" }, "207": { "$ref": "#/components/responses/207refundResponsePayload" }, "400": { "$ref": "#/components/responses/error400Response" }, "401": { "$ref": "#/components/responses/error401Response" }, "403": { "$ref": "#/components/responses/error403Response" }, "404": { "$ref": "#/components/responses/error404Response" }, "409": { "$ref": "#/components/responses/error409Response" }, "415": { "$ref": "#/components/responses/error415Response" }, "429": { "$ref": "#/components/responses/error429Response" }, "500": { "$ref": "#/components/responses/error500Response" }, "503": { "$ref": "#/components/responses/error503Response" }, "504": { "$ref": "#/components/responses/error504Response" } } } } }, "components": { "schemas": { "tiersEnabledWalletAndAccountTransactionResponse": { "type": "object", "required": [ "walletTransactions", "accountTransactions" ], "properties": { "walletTransactions": { "type": "array", "nullable": true, "description": "Wallet Transaction(s) created as a result of this settle transaction.", "items": { "$ref": "#/components/schemas/walletTransactionNoBasketTypeEntity" } }, "accountTransactions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/accountTransactionEntity" } }, "tierMembershipTransactions": { "type": "array", "nullable": true, "description": "Tier Membership Transaction(s) created as a result of this transaction.", "items": { "$ref": "#/components/schemas/tierMembershipTransactionEntity" } } } }, "walletIdentityEntity": { "type": "object", "required": [ "identityId", "walletId", "type", "friendlyName", "value", "safeValue", "secret", "dates", "meta", "state", "status", "dateCreated", "lastUpdated", "mobileWallet" ], "properties": { "identityId": { "type": "string", "description": "EES AIR Wallet Identity ID" }, "walletId": { "type": "string", "description": "EES AIR Wallet ID" }, "type": { "type": "string", "description": "Type of the Identity, list of possible enum values could be defined per Client as part of the Onboarding process." }, "friendlyName": { "type": "string", "description": "Wallet Identity friendly name" }, "value": { "type": "string", "description": "Wallet Identity value" }, "safeValue": { "type": "string", "description": "Identity Safe Value (e.g. \"original value salted and hashed\") - safeValue could be than used in external systems like analytics, referencing original identity, provide uniqueness within a retailer, but without exposing sensitive information like card number." }, "secret": { "type": "string", "description": "Wallet Identity secret" }, "dates": { "$ref": "#/components/schemas/datesEntity" }, "meta": { "$ref": "#/components/schemas/metaEntity" }, "state": { "type": "string", "description": "Wallet Identity state, list of possible values could be defined and set-up per Client during Onboarding process." }, "status": { "type": "string", "description": "Identity status", "enum": [ "ACTIVE", "DELETED", "SUSPENDED", "LOST", "STOLEN", "INACTIVE" ] }, "dateCreated": { "description": "Date this identity was created", "type": "string", "format": "date-time" }, "lastUpdated": { "description": "Date this identity was last updated", "type": "string", "format": "date-time" }, "mobileWallet": { "description": "A url that can be used to add this identity to a mobile wallet (like Apple Wallet and Google Pay)", "type": "string" } } }, "accountTransactionEntity": { "type": "object", "description": "Object representing an account transaction.", "required": [ "accountTransactionId", "accountId", "parentAccountTransactionId", "event", "value", "source", "transactionDetails", "balancesBefore", "balancesAfter", "properties", "dateCreated", "lastUpdated" ], "properties": { "accountTransactionId": { "type": "string", "description": "The account transaction ID.", "nullable": false }, "accountId": { "type": "string", "description": "The account id related to this transaction.", "nullable": false }, "parentAccountTransactionId": { "type": "string", "description": "The parent account transaction.", "nullable": true }, "event": { "type": "string", "description": "The type of transaction.", "nullable": false, "enum": [ "CREATE", "REDEEM", "LOCK", "UNLOCK", "UNREDEEM", "VERIFY", "ACTIVATE", "INACTIVATE", "REACTIVATE", "LOAD", "CREDIT", "DEBIT", "BALANCE", "INVALIDATE", "BLOCK", "UNBLOCK", "RESEND", "STOLEN", "CANCEL", "VOID", "REISSUE", "REFUND", "TRANSFER", "TRANSFER_IN", "TOPUP", "AUTOTOPUP", "STAMP", "SPEND" ] }, "value": { "type": "integer", "format": "int32", "description": "The value related to this Account Transaction. Typically, if an account transaction like credit was executed with a value, then this value will be stored here. For Continuity, however, this value should always be 0, and the same for Coupon (since there is no value for a coupon)." }, "source": { "type": "string", "nullable": false, "description": "The source of this transaction e.g. from a client (1), or triggered automatically (2) from within EES AIR (e.g. auto-top-up or the incrementation of Quest balances).", "enum": [ 1, 2 ] }, "transactionDetails": { "type": "object", "nullable": true, "description": "An simple object of key value pairs representing the transaction details." }, "balancesBefore": { "$ref": "#/components/schemas/accountTransactionBalancesHistoryEntity" }, "balancesAfter": { "$ref": "#/components/schemas/accountTransactionBalancesHistoryEntity" }, "properties": { "type": "object", "description": "Properties related to the account transaction.", "nullable": true }, "dateCreated": { "description": "Date-time (ATOM format) this account transaction was created", "type": "string", "format": "date-time", "nullable": false }, "lastUpdated": { "description": "Date-time (ATOM format) this account transaction was last updated", "type": "string", "format": "date-time", "nullable": false } } }, "tierMembershipTransactionEntity": { "type": "object", "required": [ "tierMembershipTransactionId", "tierMembershipId", "transactionType", "parentTierMembershipTransactionId", "walletTransactionId", "dateCreated", "lastUpdated", "actions" ], "properties": { "tierMembershipTransactionId": { "type": "string", "nullable": false, "description": "The ID of the tier membership Transaction." }, "tierMembershipId": { "type": "string", "nullable": false, "description": "The ID of the tier membership related to this transaction." }, "transactionType": { "type": "string", "nullable": false, "description": "The type of this tier membership transaction.", "enum": [ "CREDIT", "DEBIT", "ADJUSTMENT", "MOVE", "RESET" ] }, "parentTierMembershipTransactionId": { "type": "string", "nullable": true, "description": "The ID of any TierMembershipTransaction this is the child of." }, "walletTransactionId": { "type": "string", "nullable": false, "description": "The ID of the walletTransaction that contains this transaction." }, "dateCreated": { "description": "Time the transaction was created.", "type": "string", "format": "date-time" }, "lastUpdated": { "description": "Time the transaction was updated.", "type": "string", "format": "date-time" }, "actions": { "type": "array", "nullable": false, "items": { "type": "object", "description": "The actions to be taken to complete this tier membership transaction.", "properties": { "balanceType": { "type": "string", "description": "The type of balance to be changed.", "enum": [ "POINTS", "TRANSACTIONS", "SPEND" ] }, "amount": { "type": "integer", "description": "The amount to change the balance by." }, "balanceBefore": { "type": "integer", "description": "The balance before this transaction takes place." }, "balanceAfter": { "type": "integer", "description": "The balance after this transaction takes place." } } } } } }, "walletTransactionBaseEntity": { "type": "object", "required": [ "walletTransactionId", "parentWalletTransactionId", "walletId", "reference", "identityId", "type", "status", "meta", "state", "transactionDateTime", "expiryDate", "accounts", "channel", "location", "dateCreated", "lastUpdated" ], "properties": { "walletTransactionId": { "type": "string", "description": "Wallet Transaction ID", "nullable": false }, "parentWalletTransactionId": { "type": "string", "description": "Parent Wallet Transaction ID", "nullable": true }, "walletId": { "type": "string", "description": "Wallet ID", "nullable": true }, "reference": { "type": "string", "description": "Calling party's reference to this transaction", "nullable": true }, "identityId": { "type": "string", "description": "The Identity ID responsible for this transaction.", "nullable": true }, "identity": { "$ref": "#/components/schemas/walletIdentityEntity" }, "type": { "type": "string", "description": "Transaction Type, defined per retailer", "nullable": true }, "status": { "type": "string", "description": "Transaction status", "nullable": false, "enum": [ "ACTIVE", "SETTLED", "EXPIRED", "CANCELLED", "DELETED", "PURGED", "FULFILLING", "FULFILLED" ] }, "meta": { "$ref": "#/components/schemas/metaEntity" }, "state": { "type": "string", "description": "Transaction state", "nullable": true }, "transactionDateTime": { "type": "string", "format": "date-time", "description": "Transaction date-time in ATOM format.", "nullable": false }, "transactionDateTimeOffset": { "type": "string", "format": "string", "description": "The offset of the date-time from UTC in format \"+00:00\".", "nullable": false }, "expiryDate": { "type": "string", "format": "date-time", "description": "Transaction Expiry Timestamp (date-time in ATOM format), when transaction should expiry and automatically be settled.", "nullable": true }, "accounts": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "accountId", "accountTransactionId" ], "properties": { "accountId": { "type": "string", "description": "Account ID", "nullable": false }, "accountTransactionId": { "type": "string", "description": "Account Transaction ID", "nullable": false } } } }, "channel": { "type": "string", "description": "Channel used for Transaction creation or update" }, "location": { "$ref": "#/components/schemas/locationResponseEntity" }, "dateCreated": { "description": "Date this Wallet Transaction was created", "type": "string", "format": "date-time" }, "lastUpdated": { "description": "Date this Wallet Transaction was last updated", "type": "string", "format": "date-time" } } }, "walletTransactionNoBasketTypeEntity": { "allOf": [ { "$ref": "#/components/schemas/walletTransactionBaseEntity" }, { "type": "object", "required": [ "basket" ], "properties": { "basket": { "$ref": "#/components/schemas/walletTransactionBasketNoTypeEntity" } } } ] }, "metaEntity": { "type": "object", "description": "Key-Value object, please note key name length should be less then 255 characters and key values should be less then 255 characters" }, "adjustmentRulesBasketEntity": { "type": "object", "properties": { "externalAdjustment": { "type": "boolean", "nullable": false, "description": "Whether a discount has already been applied to this basket by a POS before calling EE.
This is purely for information and no action is taken with the data." }, "externalAdjustmentReason": { "type": "string", "description": "An external reason why a discount has already been applied to this basket by a POS before calling EE.
This is purely for information and no action is taken with the data." }, "ignore": { "type": "boolean", "nullable": false, "description": "If set to true the transaction is not eligible for any additional basket level discounts." } } }, "adjustmentRulesItemEntity": { "type": "object", "properties": { "externalAdjustment": { "type": "boolean", "nullable": false, "description": "Whether a discount has already been applied to this item by a POS before calling EE.
This is purely for information and no action is taken with the data." }, "externalAdjustmentReason": { "type": "string", "description": "An external reason why a discount has already been applied to this item by a POS before calling EE.
This is purely for information and no action is taken with the data." }, "ignore": { "type": "boolean", "nullable": false, "description": "If set to true the item is not eligible for any additional product level discounts however it is still included in the qualification of any basket level discounts." } } }, "reportingEntity": { "type": "object", "nullable": true, "properties": { "byOutlet": { "type": "array", "nullable": true, "description": "Reporting values of coupon redemptions and scheme base earn by outlet", "items": { "type": "object", "properties": { "resultsType": { "type": "string", "format": "string", "description": "Shows whether the results are from Adjudication or Adjustment", "nullable": false, "enum": [ "ADJUDICATION", "ADJUSTMENT" ] }, "redemptionPartnerIncomingIdentifier": { "type": "string", "format": "string", "description": "Product's Redemption Partner's Incoming Identifier", "nullable": true }, "outletIncomingIdentifier": { "type": "string", "format": "string", "description": "Incoming Identifier for Outlet", "nullable": true }, "resourceId": { "type": "string", "format": "string", "description": "EES AIR Campaign or Scheme Id", "nullable": false }, "type": { "type": "string", "format": "string", "nullable": false, "enum": [ "REDEEM", "EARN" ] }, "value": { "type": "integer", "format": "int32", "description": "Value of transaction" }, "accountTransactionId": { "type": "string", "format": "string", "description": "Account Transaction Id" } } } } } }, "fulfilledBaseEarnEntity": { "description": "Records the base earn points rewarded to customer during mid fulfil requests.", "type": "array", "items": { "type": "object", "properties": { "targetedAccountId": { "type": "string", "format": "string", "nullable": false, "description": "EES AIR Account ID." }, "points": { "type": "integer", "format": "int32", "nullable": false, "default": 0, "description": "Total value of base earn points rewarded." } } } }, "expectedPointsEntity": { "description": "Indicates the intended base earn and credits for any Scheme (during fulfil flow), along with whether these points will go into the `pending` bucket. N.B. Even if all coupons are not redeemed and threshold is not met, points will still go `pending`.", "type": "array", "items": { "type": "object", "properties": { "schemeId": { "type": "string", "format": "string", "nullable": false, "description": "Scheme ID which the points relate to." }, "earn": { "type": "integer", "format": "int32", "nullable": false, "default": 0, "description": "Total value of base earn points." }, "credit": { "type": "integer", "format": "int32", "nullable": false, "default": 0, "description": "Total value of points to be credited." }, "isPending": { "type": "boolean", "nullable": false, "default": false, "description": "Indicated whether the points will be put into `pending`." } } } }, "qualifiesResultsEntity": { "description": "If an offer was buy a pizza and get a free garlic bread, the pizza would have this entity against it.", "type": "array", "items": { "type": "object", "properties": { "totalMatchingUnits": { "type": "integer", "format": "int32", "description": "The number of products forming part of the offer's qualification." }, "totalMatchingSpend": { "type": "integer", "format": "int32", "description": "The monetary value this product contributes towards the offer's qualification." }, "totalOverallMatchingSpend": { "type": "integer", "format": "int32", "description": "The monetary value this product contributes towards the offer's overall qualification across valid Redemption Partners." }, "instanceId": { "type": "string", "format": "string", "description": "The reference back to the offer reward which these qualifiers relate." } } } }, "contributionResultsEntity": { "description": "If an offer was spend £30 get £5 off, this entity would be against each of the products contributing to the £5 off, with their combined `value`s adding up to the £5.", "type": "array", "nullable": true, "items": { "type": "object", "properties": { "value": { "type": "integer", "format": "int32", "description": "The proportional contribution to the discount/points given" }, "instanceId": { "type": "string", "format": "string", "description": "The reference back to the offer which these items contributed" } } } }, "adjudicationResultsEntity": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "description": "EES Resource Type", "nullable": false, "enum": [ "CAMPAIGN", "PROGRAMME", "SCHEME" ] }, "resourceId": { "type": "string", "format": "string", "description": "EES AIR Resource ID (Campaign ID, Programme ID, Scheme ID)", "nullable": false }, "playOrderPosition": { "type": "integer", "format": "int32", "nullable": true, "description": "The exact position the offer was triggered during analysis" }, "success": { "type": "boolean", "nullable": true }, "type": { "type": "string", "description": "Operation Type", "nullable": false, "enum": [ "redeem", "credit", "debit", "earn", "spend" ] }, "value": { "type": "integer", "format": "int32", "nullable": false, "description": "Operation Amount (please note: value and balances attributes are mutually exclusive)" }, "balances": { "$ref": "#/components/schemas/accountBalancesEntity" }, "isRefundable": { "type": "boolean", "nullable": false, "description": "Boolean Flag indicating if this offer should be refundable" }, "isUnredeemable": { "type": "boolean", "nullable": false, "description": "Boolean Flag indicating if this offer should be Unredeemable" }, "relatedAccountIds": { "type": "array", "items": { "type": "string", "format": "string", "description": "EES AIR Account ID" } }, "relatedWalletId": { "type": "string", "format": "string", "description": "EES AIR Wallet ID.", "nullable": true }, "targetedAccountId": { "type": "string", "format": "string", "description": "EES AIR Account ID" }, "targetedWalletId": { "type": "string", "format": "string", "description": "EES AIR Wallet ID.", "nullable": true }, "totalMatchingUnits": { "type": "integer", "nullable": true, "format": "int32", "description": "The minimum number of products required to trigger offer" }, "totalRewardUnits": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of units the reward applies to within this item." }, "rewardType": { "type": "string", "nullable": true, "enum": [ "standard", "boltOn" ], "description": "Indicates whether a `credit` type was a standard reward or is a bolt on. All other operations will have be `null`, when present." } } } }, "adjustmentResultsEntity": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "description": "EES Resource Type", "nullable": false, "enum": [ "CAMPAIGN" ] }, "resourceId": { "type": "string", "format": "string", "description": "EES AIR Resource ID (Campaign ID, Programme ID, Scheme ID)", "nullable": false }, "resourceReference": { "type": "string", "format": "string", "description": "The EES AIR Resource Reference (Campaign Reference) relating to this adjustment result. Only included for external adjustment results.", "nullable": false }, "playOrderPosition": { "type": "integer", "format": "int32", "nullable": true, "description": "The exact position the offer was triggered during analysis" }, "success": { "type": "boolean", "nullable": true }, "type": { "type": "string", "description": "Operation Type", "nullable": false, "enum": [ "redeem", "createRedeem" ] }, "value": { "type": "integer", "format": "int32", "nullable": false, "description": "Operation Amount" }, "isUnredeemable": { "type": "boolean", "nullable": false, "description": "Boolean Flag indicating if this offer should be Unredeemable" }, "relatedAccountIds": { "type": "array", "items": { "type": "string", "format": "string", "description": "EES AIR Account ID" } }, "targetedAccountId": { "type": "string", "format": "string", "description": "EES AIR Account ID" }, "targetedWalletId": { "type": "string", "format": "string", "description": "EES AIR Wallet ID. Nullable", "nullable": true }, "multiItem": { "type": "array", "items": { "type": "string", "format": "string", "description": "Used for coupons that can span multiple SKU's in a basket, links basket items together based on SKU" } }, "totalDiscountAmount": { "type": "integer", "format": "int32", "description": "The monetary effect of the discount in the lowest unit of currency" }, "totalMatchingUnits": { "type": "integer", "format": "int32", "description": "The number of products the adjustment was applied to" }, "instanceId": { "type": "string", "format": "string", "description": "A mechanism to distinguish each individual reward that has been given for any account" }, "totalRewardUnits": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of units the reward applies to within this item." } } } }, "tenderResultsEntity": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "description": "EES Resource Type", "nullable": false, "enum": [ "CAMPAIGN" ] }, "resourceId": { "type": "string", "format": "string", "description": "EES AIR Resource ID (Campaign ID, Programme ID, Scheme ID)", "nullable": false }, "playOrderPosition": { "type": "integer", "format": "int32", "nullable": true, "description": "The exact position the offer was triggered during analysis" }, "success": { "type": "boolean", "nullable": true }, "type": { "type": "string", "description": "Operation Type", "nullable": false, "enum": [ "redeem", "createRedeem" ] }, "value": { "type": "integer", "format": "int32", "nullable": false, "description": "Operation Amount" }, "isUnredeemable": { "type": "boolean", "nullable": false, "description": "Boolean Flag indicating if this offer should be Unredeemable" }, "relatedAccountIds": { "type": "array", "items": { "type": "string", "format": "string", "description": "EES AIR Account ID" } }, "targetedAccountId": { "type": "string", "format": "string", "description": "EES AIR Account ID" }, "targetedWalletId": { "type": "string", "format": "string", "description": "EES AIR Wallet ID. Nullable", "nullable": true }, "multiItem": { "type": "array", "items": { "type": "string", "format": "string", "description": "Used for coupons that can span multiple SKU's in a basket, links basket items together based on SKU" } }, "totalTenderAmount": { "type": "integer", "format": "int32", "description": "The amount of tender value in the lowest unit of currency" } } } }, "datesEntity": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "accountBalancesEntity": { "type": "object", "description": "The object of balances. Some balances only apply to certain types of accounts. See notes below on balances.\n", "properties": { "available": { "type": "integer", "description": "The available balance. This is applicable for all account types, except POINTS and CONTINUITY, which uses its own balance keys. For ECOUPON account type this property will be returned and will be equal to zero.\n" }, "refundable": { "type": "integer", "description": "The refundable balance. This is applicable for all account types except POINTS and CONTINUITY, but is not used during account creation. For an Account Entity, the amount displayed here is the total refundable balance available. Please note for ECOUPON account type this property will be returned and equal to zero.\n" }, "totalSpend": { "type": "integer", "description": "The total spend balance. Applicable only to accounts of type CONTINUITY.\n" }, "transactionCount": { "type": "integer", "description": "The transaction counter. Applicable only to accounts of type CONTINUITY.\n" }, "current": { "type": "integer", "description": "The current balance. Applicable only to accounts of type POINTS and STAMP. If current is not provided on creation, this will be set to 0.\n" }, "usable": { "type": "integer", "description": "The usable balance. Applicable only to accounts of type POINTS. If usable is not provided on creation, this will be set to 0.\n" }, "locked": { "type": "integer", "description": "The locked balance. Applicable only to accounts of type POINTS. If locked is not provided on creation, this will be set to 0.\n" }, "lifetime": { "type": "integer", "description": "The lifetime balance. Applicable only to accounts of type POINTS and STAMP. If lifetime is not provided on creation, this will be set to 0." }, "totalUnits": { "type": "integer", "description": "The total units purchased balance. Applicable only to accounts of type CONTINUITY.\n" } } }, "accountTransactionBalancesHistoryEntity": { "type": "object", "description": "The object of balances to show for either before or after the account transaction. Some balances only apply to certain types of accounts. See notes below on balances.\n", "properties": { "available": { "description": "The available balance. This is applicable for all account types, except STAMP, POINTS and CONTINUITY, which uses its own balance keys, and ECOUPON, which has no concept of a balance.\n", "type": "integer" }, "refundable": { "description": "The refundable balance. This is applicable for all account types, except STAMP, ECOUPON, POINTS and CONTINUITY.\n", "type": "integer" }, "current": { "type": "integer", "description": "The current balance. Applicable only to accounts of type Points and Stamp.\n" }, "lifetime": { "type": "integer", "description": "The lifetime balance. Applicable only to accounts of type Points and Stamp.\n" }, "totalSpend": { "type": "integer", "description": "The total spend balance. Applicable only to accounts of type Continuity.\n" }, "transactionCount": { "type": "integer", "description": "The transaction counter. Applicable only to accounts of type Continuity.\n" } } }, "walletTransactionBasketNoTypeEntity": { "anyOf": [ { "$ref": "#/components/schemas/standardBasketNoTypeEntity" }, { "$ref": "#/components/schemas/enrichedBasketNoTypeEntity" } ] }, "locationEntity": { "type": "object", "nullable": false, "required": [ "incomingIdentifier" ], "properties": { "incomingIdentifier": { "type": "string", "format": "string", "nullable": false, "description": "Optional Outlet Incoming Identifier allowing to override location arisen from used API Key of where this transaction has happened" }, "parentIncomingIdentifier": { "type": "string", "format": "string", "nullable": false, "description": "Outlet's Parent unit Incoming Identifier allowing to uniquely identify an Outlet override arisen from used API Key location where this transaction has happened. Please note this optional JSON attribute should be used in case incoming identifiers are not unique within a Client's Hierarchy" } } }, "locationResponseEntity": { "type": "object", "properties": { "storeId": { "type": "string", "format": "string", "description": "The Incoming Identifier of the Outlet." }, "storeParentId": { "type": "string", "format": "string", "description": "The Incoming Identifier of the Outlet's Parent Unit." } } }, "standardPaymentEntity": { "type": "array", "nullable": true, "items": { "type": "object", "required": [ "tenderType", "amount" ], "properties": { "tenderType": { "type": "string", "format": "string", "description": "Tender type - predefined by Eagle Eye" }, "amount": { "type": "integer", "format": "int32", "description": "Monetary amount of payment in lowest unit of currency" }, "bin": { "type": "string", "format": "string", "description": "The bin for the tender" }, "identifier": { "type": "string", "format": "string", "description": "An identifying value of what was scanned, could be a token, barcode, gift-card" } } } }, "enrichedPaymentEntity": { "type": "array", "nullable": true, "description": "Similar to standardPaymentEntity, except that any _tender_ offers used during adjustment, have an entry injected here, stipulating the tender amount to take off basket", "items": { "type": "object", "required": [ "tenderType", "amount" ], "properties": { "tenderType": { "type": "string", "format": "string", "description": "Tender type - predefined by Eagle Eye, including a further type of _tenderCoupon_" }, "amount": { "type": "integer", "format": "int32", "description": "Monetary amount of payment/tender in lowest unit of currency" }, "bin": { "type": "string", "format": "string", "description": "The bin for the tender" }, "identifier": { "type": "string", "format": "string", "description": "An identifying value of what was scanned, could be a token, barcode, gift-card" }, "accountId": { "type": "string", "format": "string", "description": "The EE AIR Account ID (only populated when tender is owned by EE)" } } } }, "bounceBackResultsEntity": { "type": "array", "deprecated": true, "items": { "type": "object", "properties": { "resourceType": { "type": "string", "description": "EES Resource Type", "nullable": false, "enum": [ "CAMPAIGN" ] }, "resourceId": { "type": "string", "format": "string", "description": "EES AIR Campaign Id", "nullable": false }, "playOrderPosition": { "type": "integer", "format": "int32", "nullable": true, "description": "The exact position the offer was triggered during analysis" }, "success": { "type": "boolean", "nullable": true }, "type": { "type": "string", "enum": [ "redeem" ] }, "value": { "type": "integer", "format": "int32", "description": "Value of transaction" }, "balances": { "$ref": "#/components/schemas/accountBalancesEntity" }, "isRefundable": { "type": "boolean", "nullable": false, "description": "Boolean Flag indicating if this offer should be refundable" }, "isUnredeemable": { "type": "boolean", "nullable": false, "description": "Boolean Flag indicating if this offer should be Unredeemable" }, "relatedAccounts": { "type": "array", "items": { "type": "string", "format": "string", "description": "EES AIR Account ID" } }, "targetedAccountId": { "type": "string", "format": "string", "description": "EES AIR Account ID" }, "targetedWalletId": { "type": "string", "format": "string", "description": "EES AIR Wallet ID.", "nullable": true } } } }, "standardBasketNoTypeEntity": { "title": "Standard Basket Entity", "type": "object", "properties": { "summary": { "$ref": "#/components/schemas/standardBasketSummaryEntity" }, "contents": { "$ref": "#/components/schemas/standardBasketContentsCollectionEntity" }, "payment": { "$ref": "#/components/schemas/standardPaymentEntity" } } }, "standardBasketSummaryEntity": { "type": "object", "required": [ "totalItems", "totalBasketValue" ], "properties": { "totalItems": { "type": "integer", "format": "int32", "nullable": false, "description": "Basket Items count" }, "totalBasketValue": { "type": "integer", "format": "int32", "nullable": false, "description": "Total Basket monetary Value after discounts, denominated to a smallest currency unit (e.g. for `USD` this value should be provided in `cents`)" }, "totalDiscountAmount": { "type": "object", "properties": { "promotions": { "type": "integer", "format": "int32", "description": "Promotions Discount Amount. If basket adjustment adds to discounts, this amount will be added to", "nullable": true }, "staff": { "type": "integer", "format": "int32", "description": "Staff Discount Amount", "nullable": true }, "general": { "type": "integer", "format": "int32", "description": "General Discount Amount", "nullable": true } } }, "totalQualifyingAmount": { "type": "object", "nullable": true, "minProperties": 1, "maxProperties": 4, "properties": { "points": { "type": "integer", "format": "int32", "nullable": false, "description": "Basket Monetary Value for Loyalty Points calculations" }, "baseEarn": { "type": "integer", "format": "int32", "nullable": false, "description": "Basket Monetary Value used for calculating base earn, overriding totalBasketValue. Adheres to basket discounts" }, "promotions": { "type": "integer", "format": "int32", "nullable": false, "description": "Basket Monetary Value for Promotion Offer selections" }, "discount": { "type": "integer", "format": "int32", "nullable": false, "description": "Basket Monetary Value for Discount calculations" }, "staff": { "type": "integer", "format": "int32", "nullable": false, "description": "Basket Monetary Value for Staff Discount or Promotions" } } }, "totalTaxAmount": { "type": "integer", "format": "int32", "description": "Total Tax Amount denominated to a smallest currency unit (e.g. for `USD` this value should be provided in `cents`)" }, "adjustmentRules": { "$ref": "#/components/schemas/adjustmentRulesBasketEntity" }, "adjustmentResults": { "$ref": "#/components/schemas/adjustmentResultsEntity" }, "redemptionChannel": { "description": "The redemption channel used for this request", "type": "string", "format": "string", "nullable": false } } }, "refundBasketContentsCollectionEntity": { "type": "array", "nullable": false, "items": { "type": "object", "description": "Each refund basket item must include `salesKey` (set to `REFUND`), `totalUnitCostAfterDiscount` and at least one of `sku` or `upc` (used to match the item against the original transaction).", "allOf": [ { "$ref": "#/components/schemas/standardBasketContentsCollectionEntity/items" }, { "type": "object", "required": [ "salesKey" ], "anyOf": [ { "required": [ "sku" ] }, { "required": [ "upc" ] } ], "properties": { "salesKey": { "type": "string", "enum": [ "REFUND" ], "description": "Determines the nature of the transaction, requests related to product sales, refunds, and fulfillment operations. Mandatory for each refund basket item and must be set to `REFUND`." } } } ] } }, "standardBasketContentsCollectionEntity": { "type": "array", "nullable": true, "items": { "type": "object", "required": [ "totalUnitCostAfterDiscount" ], "properties": { "sku": { "type": "string", "format": "string", "nullable": false, "description": "Item SKU. Either `sku` or `upc` should be provided to identify the product." }, "upc": { "type": "string", "format": "string", "nullable": false, "description": "Item UPC. Either `sku` or `upc` should be provided to identify the product." }, "description": { "type": "string", "format": "string", "nullable": false, "description": "Product Name" }, "redemptionPartnerIncomingIdentifier": { "type": "string", "format": "string", "nullable": true, "description": "Allows a product belonging to another redemption partner to be adjudicated alongside the calling. Must be provided if `outletIncomingIdentifier` is used." }, "outletIncomingIdentifier": { "type": "string", "format": "string", "nullable": false, "description": "The outlet the product should be adjudicated against. Belongs directly to the product's `redemptionPartnerIncomingIdentifier`. (For Future Use)" }, "groupReference": { "type": "array", "nullable": false, "description": "Allows passing in group reference for the item. This reference will be used to process the item as part of any groups with the given reference.", "items": { "type": "string" } }, "itemUnitCost": { "type": "integer", "format": "int32", "nullable": false, "description": "Item Price per unit, denominated to a smaller currency unit" }, "itemUnitMetric": { "type": "string", "description": "The metric in which the item is measure (nullable)", "enum": [ "LITRES", "GRAMS", "MILLILITERS", "KILOGRAMS", "POUNDS", "OUNCES", "PIECE", "EACH" ] }, "itemUnitCount": { "type": "integer", "format": "int32", "nullable": false, "description": "Item Quantity" }, "itemUnitDiscount": { "type": "integer", "format": "int32", "nullable": false, "description": "Discount per Item" }, "totalUnitCost": { "type": "integer", "format": "int32", "nullable": false, "description": "Total cost for this item" }, "totalUnitCostAfterDiscount": { "type": "integer", "format": "int32", "nullable": false, "description": "Total cost for this item after discount (please note this does not take into account whole basket discounts). This attribute is mandatory for every basket content item." }, "taxRate": { "type": "number", "format": "float", "nullable": false, "description": "Tax Rate (Percentage)" }, "taxAmount": { "type": "integer", "format": "int32", "nullable": false, "description": "Tax Amount for that item, denominated to a smallest currency unit" }, "adjustmentResults": { "$ref": "#/components/schemas/adjustmentResultsEntity" }, "qualifies": { "type": "object", "nullable": true, "required": [ "discount", "points" ], "properties": { "discount": { "type": "boolean", "description": "Determines if the item is eligible for basket level discounting. If false this item will not qualify for basket level discounts but still qualify for product level discounts. However this is possible to override based on the ‘ignorePreviousExcludes’ key on a campaign.\n" }, "points": { "type": "boolean", "description": "Determines if the item is eligible for Base Earn points. If false this item will not qualify for Base Earn points but still qualify for basket and product level discounts.\n" }, "offerPoints": { "type": "boolean", "description": "Determines if the item is eligible for points reward Campaigns. If false this item will not qualify for rewards points however, it remains eligible to qualify for Base Earn Points, as well as both Basket and Product-Level Discounts.\n" } } }, "meta": { "$ref": "#/components/schemas/metaEntity" }, "adjustmentRules": { "$ref": "#/components/schemas/adjustmentRulesItemEntity" }, "relatedContents": { "description": "Recursive list of contents related to the parent item with the same schema as this object.", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "format": "string", "nullable": false, "description": "Item SKU" }, "upc": { "type": "string", "format": "string", "nullable": false, "description": "Item SKU" }, "salesKey": { "type": "string", "enum": [ "SALE", "REFUND", "FULFIL" ], "default": "SALE", "description": "`SALE`/`REFUND`/`FULFIL` Flag" }, "description": { "type": "string", "format": "string", "nullable": false, "description": "Product Name" }, "itemUnitCost": { "type": "integer", "format": "int32", "nullable": false, "description": "Item Price per unit, denominated to a smaller currency unit" }, "itemUnitMetric": { "type": "string", "description": "The metric in which the item is measure (nullable)", "enum": [ "LITRES", "GRAMS", "MILLILITERS", "KILOGRAMS", "POUNDS", "OUNCES", "PIECE" ] }, "itemUnitCount": { "type": "integer", "format": "int32", "nullable": false, "description": "Item Quantity" }, "itemUnitDiscount": { "type": "integer", "format": "int32", "nullable": false, "description": "Discount per Item" }, "totalUnitCost": { "type": "integer", "format": "int32", "nullable": false, "description": "Total cost for this item" }, "totalUnitCostAfterDiscount": { "type": "integer", "format": "int32", "nullable": false, "description": "Total cost for this item after discount (please note this does not take into account whole basket discounts)" }, "taxRate": { "type": "number", "format": "float", "nullable": false, "description": "Tax Rate (Percentage)" }, "taxAmount": { "type": "integer", "format": "int32", "nullable": false, "description": "Tax Amount for that item, denominated to a smallest currency unit" }, "qualifies": { "type": "object", "nullable": true, "required": [ "discount", "points" ], "properties": { "discount": { "type": "boolean", "description": "Determines if the item is eligible for basket level discounting. If false this item will not qualify for basket level discounts but still qualify for product level discounts. However this is possible to override based on the ‘ignorePreviousExcludes’ key on a campaign.\n" }, "points": { "type": "boolean", "description": "Determines if the item is eligible for Base Earn points. If false this item will not qualify for Base Earn points but still qualify for basket and product level discounts.\n" } } }, "meta": { "$ref": "#/components/schemas/metaEntity" }, "adjustmentRules": { "$ref": "#/components/schemas/adjustmentRulesItemEntity" }, "relatedContents": { "description": "Recursive list of contents related to the parent item with the same schema as this object." } } } } } } }, "enrichedBasketContentsCollectionEntity": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "sku": { "type": "string", "format": "string", "nullable": false, "description": "Item SKU" }, "upc": { "type": "string", "format": "string", "nullable": false, "description": "Item SKU" }, "salesKey": { "type": "string", "enum": [ "SALE", "REFUND", "FULFIL" ], "default": "SALE", "description": "`SALE`/`REFUND`/`FULFIL` Flag" }, "description": { "type": "string", "format": "string", "nullable": false, "description": "Product Name" }, "itemUnitCost": { "type": "integer", "format": "int32", "nullable": false, "description": "Item Price per unit, denominated to a smaller currency unit" }, "redemptionPartnerIncomingIdentifier": { "type": "string", "format": "string", "nullable": true, "description": "Allows a product belonging to another redemption partner to be adjudicated alongside the calling. Must be provided if `outletIncomingIdentifier` is used." }, "outletIncomingIdentifier": { "type": "string", "format": "string", "nullable": false, "description": "The outlet the product should be adjudicated against. Belongs directly to the product's `redemptionPartnerIncomingIdentifier`. (For Future Use)" }, "groupReference": { "type": "array", "nullable": false, "description": "The group reference passed in for the item, used to process the item as part of any groups with the given reference.", "items": { "type": "string" } }, "itemUnitMetric": { "type": "string", "description": "The metric in which the item is measure (nullable)", "enum": [ "LITRES", "GRAMS", "MILLILITERS", "KILOGRAMS", "POUNDS", "OUNCES", "PIECE", "EACH" ] }, "itemUnitCount": { "type": "integer", "format": "int32", "nullable": false, "description": "Item Quantity" }, "itemFulfilmentCount": { "type": "integer", "format": "int32", "nullable": true, "description": "Number Of Items Fulfilled" }, "itemUnitDiscount": { "type": "integer", "format": "int32", "nullable": false, "description": "Discount per Item" }, "totalUnitCost": { "type": "integer", "format": "int32", "nullable": false, "description": "Total cost for this item" }, "totalUnitCostAfterDiscount": { "type": "integer", "format": "int32", "nullable": false, "description": "Total cost for this item after discount (please note this does not take into account whole basket discounts)" }, "taxRate": { "type": "number", "format": "float", "nullable": false, "description": "The rate of tax being applied to this item (percentage)" }, "taxAmount": { "type": "integer", "format": "int32", "nullable": false, "description": "Tax Amount for that item, denominated to a smallest currency unit" }, "qualifies": { "type": "object", "nullable": true, "required": [ "discount", "points" ], "properties": { "discount": { "type": "boolean", "description": "Determines if the item is eligible for discounting" }, "points": { "type": "boolean", "description": "Determines if the item is eligible for points" } } }, "meta": { "$ref": "#/components/schemas/metaEntity" }, "adjustmentRules": { "$ref": "#/components/schemas/adjustmentRulesItemEntity" }, "adjustmentResults": { "$ref": "#/components/schemas/adjustmentResultsEntity" }, "tenderResults": { "$ref": "#/components/schemas/tenderResultsEntity" }, "bounceBackResults": { "$ref": "#/components/schemas/bounceBackResultsEntity" }, "qualifiesResults": { "$ref": "#/components/schemas/qualifiesResultsEntity" }, "contributionResults": { "$ref": "#/components/schemas/contributionResultsEntity" }, "adjudicationResults": { "$ref": "#/components/schemas/adjudicationResultsEntity" }, "relatedContents": { "type": "array", "description": "Recursive list of contents related to the parent item with the same schema as this object.", "items": { "type": "object", "properties": { "sku": { "type": "string", "format": "string", "nullable": false, "description": "Item SKU" }, "upc": { "type": "string", "format": "string", "nullable": false, "description": "Item SKU" }, "salesKey": { "type": "string", "enum": [ "SALE", "REFUND", "FULFIL" ], "default": "SALE", "description": "`SALE`/`REFUND`/`FULFIL` Flag" }, "description": { "type": "string", "format": "string", "nullable": false, "description": "Product Name" }, "itemUnitCost": { "type": "integer", "format": "int32", "nullable": false, "description": "Item Price per unit, denominated to a smaller currency unit" }, "itemUnitMetric": { "type": "string", "description": "The metric in which the item is measure (nullable)", "enum": [ "LITRES", "GRAMS", "MILLILITERS", "KILOGRAMS", "POUNDS", "OUNCES", "PIECE" ] }, "itemUnitCount": { "type": "integer", "format": "int32", "nullable": false, "description": "Item Quantity" }, "itemFulfilmentCount": { "type": "integer", "format": "int32", "nullable": true, "description": "Number Of Items Fulfilled" }, "itemUnitDiscount": { "type": "integer", "format": "int32", "nullable": false, "description": "Discount per Item" }, "totalUnitCost": { "type": "integer", "format": "int32", "nullable": false, "description": "Total cost for this item" }, "totalUnitCostAfterDiscount": { "type": "integer", "format": "int32", "nullable": false, "description": "Total cost for this item after discount (please note this does not take into account whole basket discounts)" }, "taxRate": { "type": "number", "format": "float", "nullable": false, "description": "The rate of tax being applied to this item (percentage)" }, "taxAmount": { "type": "integer", "format": "int32", "nullable": false, "description": "Tax Amount for that item, denominated to a smallest currency unit" }, "qualifies": { "type": "object", "nullable": true, "required": [ "discount", "points" ], "properties": { "discount": { "type": "boolean", "description": "Determines if the item is eligible for discounting" }, "points": { "type": "boolean", "description": "Determines if the item is eligible for points" } } }, "meta": { "$ref": "#/components/schemas/metaEntity" }, "adjustmentRules": { "$ref": "#/components/schemas/adjustmentRulesItemEntity" }, "adjustmentResults": { "$ref": "#/components/schemas/adjustmentResultsEntity" }, "tenderResults": { "$ref": "#/components/schemas/tenderResultsEntity" }, "bounceBackResults": { "$ref": "#/components/schemas/bounceBackResultsEntity" }, "qualifiesResults": { "$ref": "#/components/schemas/qualifiesResultsEntity" }, "adjudicationResults": { "$ref": "#/components/schemas/adjudicationResultsEntity" }, "relatedContents": { "description": "Recursive list of contents related to the parent item with the same schema as this object." } } } } } } }, "tierMembershipResultsEntity": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "tierMembershipId": { "type": "string", "description": "The ID of the tierMembership." }, "type": { "type": "string", "enum": [ "credit" ] }, "balances": { "type": "object", "properties": { "points": { "type": "integer", "nullable": false, "format": "int32", "description": "The number of tier membership points awarded to this membership in this transaction." }, "transactions": { "type": "integer", "nullable": false, "format": "int32", "description": "The number of tier membership transactions completed." }, "spend": { "type": "integer", "nullable": false, "format": "int32", "description": "The total spend counting towards tier membership." } } }, "success": { "type": "boolean", "nullable": true, "description": "If this has been successfully settled (always null in open response)." } } } }, "enrichedBasketSummaryResultsEntity": { "title": "Transaction Summary Results Entity", "type": "object", "properties": { "pointsByScheme": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "points": { "$ref": "#/components/schemas/resultsPointsEntity" } } } }, "points": { "$ref": "#/components/schemas/resultsPointsEntity" }, "tiers": { "type": "object", "properties": { "points": { "description": "The total amount of tier membership points for this transaction.", "type": "integer", "format": "int32", "nullable": false }, "transactions": { "description": "The total number of tier transactions to be awarded for this transaction.", "type": "integer", "format": "int32", "nullable": false }, "spend": { "description": "The total amount of spend to credit for this transaction.", "type": "integer", "format": "int32", "nullable": false } } } } }, "resultsPointsEntity": { "type": "object", "properties": { "spend": { "description": "Total value of points spent during transaction.", "type": "integer", "format": "int32", "nullable": false }, "debit": { "description": "Total value of points debited during transaction.", "type": "integer", "format": "int32", "nullable": false }, "refund": { "description": "Total value of points clawed-back during refund transaction.", "type": "integer", "format": "int32", "nullable": false }, "totalPointsTaken": { "description": "Sum of all negative balance actions (spend + debit + refund).", "type": "integer", "format": "int32", "nullable": false }, "earn": { "description": "Total value of points earned during transaction.", "type": "integer", "format": "int32", "nullable": false }, "credit": { "description": "Total value of points credited during transaction.", "type": "integer", "format": "int32", "nullable": false }, "totalPointsGiven": { "description": "Sum of all positive balance actions (earn + credit).", "type": "integer", "format": "int32", "nullable": false }, "totalMonetaryValue": { "description": "Monetary value of points using Scheme rules.", "type": "integer", "format": "int32", "nullable": false }, "redemptionChannel": { "description": "The redemption channel used for this request.", "type": "string", "format": "string", "nullable": false } } }, "enrichedBasketNoTypeEntity": { "title": "Enriched Basket Entity", "type": "object", "required": [ "summary" ], "properties": { "summary": { "type": "object", "required": [ "totalItems", "totalBasketValue" ], "properties": { "totalItems": { "type": "integer", "format": "int32", "nullable": false, "description": "Basket Items count" }, "totalBasketValue": { "type": "integer", "format": "int32", "nullable": false, "description": "Total Basket monetary Value after discounts, denominated to a smallest currency unit (e.g. for `USD` this value should be provided in `cents`)" }, "totalQualifyingAmount": { "type": "object", "nullable": true, "minProperties": 1, "maxProperties": 4, "properties": { "points": { "type": "integer", "format": "int32", "nullable": true, "description": "Basket Monetary Value for Loyalty Points calculations" }, "baseEarn": { "type": "integer", "format": "int32", "nullable": false, "description": "Basket Monetary Value used for calculating base earn, overriding totalBasketValue. Adheres to basket discounts" }, "promotions": { "type": "integer", "format": "int32", "nullable": true, "description": "Basket Monetary Value for Promotion Offer selections" }, "discount": { "type": "integer", "format": "int32", "nullable": true, "description": "Basket Monetary Value for Discount calculations" }, "staff": { "type": "integer", "format": "int32", "nullable": true, "description": "Basket Monetary Value for Staff Discount or Promotions" } } }, "totalTaxAmount": { "type": "integer", "format": "int32", "nullable": true, "description": "Total Tax Amount denominated to a smallest currency unit (e.g. for `USD` this value should be provided in `cents`)" }, "totalDiscountAmount": { "type": "object", "properties": { "promotions": { "type": "integer", "format": "int32", "description": "Promotions Discount Amount. If basket adjustment adds to discounts, this amount will be added to", "nullable": true }, "staff": { "type": "integer", "format": "int32", "description": "Staff Discount Amount", "nullable": true }, "general": { "type": "integer", "format": "int32", "description": "General Discount Amount", "nullable": true } } }, "reporting": { "$ref": "#/components/schemas/reportingEntity" }, "fulfilledBaseEarn": { "$ref": "#/components/schemas/fulfilledBaseEarnEntity" }, "expectedPoints": { "$ref": "#/components/schemas/expectedPointsEntity" }, "adjustmentRules": { "$ref": "#/components/schemas/adjustmentRulesBasketEntity" }, "tenderResults": { "$ref": "#/components/schemas/tenderResultsEntity" }, "adjustmentResults": { "$ref": "#/components/schemas/adjustmentResultsEntity" }, "bounceBackResults": { "$ref": "#/components/schemas/bounceBackResultsEntity" }, "qualifiesResults": { "$ref": "#/components/schemas/qualifiesResultsEntity" }, "adjudicationResults": { "$ref": "#/components/schemas/adjudicationResultsEntity" }, "results": { "$ref": "#/components/schemas/enrichedBasketSummaryResultsEntity" }, "tierMembershipResults": { "$ref": "#/components/schemas/tierMembershipResultsEntity" }, "redemptionChannel": { "description": "The redemption channel used for this request", "type": "string", "format": "string", "nullable": false } } }, "contents": { "$ref": "#/components/schemas/enrichedBasketContentsCollectionEntity" }, "payment": { "$ref": "#/components/schemas/enrichedPaymentEntity" }, "analysedDateTime": { "type": "string", "format": "ees-date-time", "description": "Basket Analysis Date-Time in ATOM format", "nullable": false } } }, "defaultErrorEntity": { "type": "object", "properties": { "errorCode": { "type": "string", "description": "EES AIR Error Code", "enum": [ "NF", "IR", "U", "AF", "AT", "IFU", "CE", "IPR", "MNA", "MPA", "P", "ALR", "CX", "CI", "CP", "CR", "CU", "CORQ", "CTNR", "DSN", "IW", "RW", "VURC", "VURI", "FES", "IOC", "AA", "ILA", "IP", "LIR", "LNA", "LPR", "MAC", "MTLE", "MLV", "MAR", "OC", "RWI", "TEXP", "TULR", "UAS", "UV", "VA", "VC", "VXP", "VI", "VL", "VNL", "VPUF", "VSM", "VUA", "VU", "ITID", "WTF", "IH", "RFL" ] }, "errorMessage": { "type": "string", "format": "string", "description": "Human Friendly Error Message" } }, "x-enum": [ { "errorCode": "NF", "errorMessage": "Not Found" }, { "errorCode": "IR", "errorMessage": "Invalid Request" }, { "errorCode": "U", "errorMessage": "Unknown Error" }, { "errorCode": "AF", "errorMessage": "Authorisation Failed" }, { "errorCode": "AT", "errorMessage": "Account Type" }, { "errorCode": "IFU", "errorMessage": "Insufficient Funds" }, { "errorCode": "CE", "errorMessage": "Configuration Error" }, { "errorCode": "IPR", "errorMessage": "IP Address Rejected" }, { "errorCode": "MNA", "errorMessage": "Method Not Allowed" }, { "errorCode": "MPA", "errorMessage": "Missing Parameter" }, { "errorCode": "P", "errorMessage": "Privileges" }, { "errorCode": "ALR", "errorMessage": "Account Limit Reached" }, { "errorCode": "CX", "errorMessage": "Campaign Expired" }, { "errorCode": "CI", "errorMessage": "Campaign Inactive" }, { "errorCode": "CP", "errorMessage": "Campaign Pending" }, { "errorCode": "CR", "errorMessage": "Campaign Removed" }, { "errorCode": "CU", "errorMessage": "Campaign Unknown" }, { "errorCode": "CORQ", "errorMessage": "Consumer Required" }, { "errorCode": "CTNR", "errorMessage": "Consumer Type Not Recognized" }, { "errorCode": "DSN", "errorMessage": "Duplicated Serial Number" }, { "errorCode": "IW", "errorMessage": "Voucher Can Not Be Created" }, { "errorCode": "RW", "errorMessage": "Voucher Can Not Be Redeemed" }, { "errorCode": "VURC", "errorMessage": "No Voucher Available to Redeem for Campaign" }, { "errorCode": "VURI", "errorMessage": "No Voucher Available to Redeem for this Identity" }, { "errorCode": "FES", "errorMessage": "Scheduling Format Incorrect" }, { "errorCode": "IOC", "errorMessage": "Improper Offer Configuration" }, { "errorCode": "AA", "errorMessage": "Invalid Access to API Method" }, { "errorCode": "ILA", "errorMessage": "Invalid Load Amount" }, { "errorCode": "IP", "errorMessage": "Invalid Parameter" }, { "errorCode": "LIR", "errorMessage": "Outlet Identifier Required" }, { "errorCode": "LNA", "errorMessage": "Outlet Not Allowed" }, { "errorCode": "LPR", "errorMessage": "Outlet Prohibited by Campaign Settings" }, { "errorCode": "MAC", "errorMessage": "Maximum Number of Code Variations" }, { "errorCode": "MTLE", "errorMessage": "Max Active Tokens Limit Exceeded" }, { "errorCode": "MLV", "errorMessage": "Maximum Voucher Value Exceeded" }, { "errorCode": "MAR", "errorMessage": "Minimum Amount Required" }, { "errorCode": "OC", "errorMessage": "Campaign has no Offer" }, { "errorCode": "RWI", "errorMessage": "Token can not be Redeemed at this time. Blocked by redemption windows." }, { "errorCode": "TEXP", "errorMessage": "Token Expired" }, { "errorCode": "TULR", "errorMessage": "Token Usage Limit Reached" }, { "errorCode": "UAS", "errorMessage": "Transaction Not Allowed by current account status" }, { "errorCode": "UV", "errorMessage": "Voucher Unknown" }, { "errorCode": "VA", "errorMessage": "Voucher already been sent" }, { "errorCode": "VC", "errorMessage": "Voucher Cancelled" }, { "errorCode": "VXP", "errorMessage": "Voucher Expired" }, { "errorCode": "VI", "errorMessage": "Voucher Invalid" }, { "errorCode": "VL", "errorMessage": "Voucher Locked" }, { "errorCode": "VNL", "errorMessage": "Voucher Not Locked" }, { "errorCode": "VPUF", "errorMessage": "Voucher You don't have privileges to unlock this token" }, { "errorCode": "VSM", "errorMessage": "Voucher Serial Mismatch" }, { "errorCode": "VUA", "errorMessage": "No vouchers available for this campaign" }, { "errorCode": "VU", "errorMessage": "Voucher already redeemed" }, { "errorCode": "ITID", "errorMessage": "Invalid Transaction ID" }, { "errorCode": "WTF", "errorMessage": "Wallet Transaction Failure" }, { "errorCode": "IH", "errorMessage": "Invalid Header set" }, { "errorCode": "RFL", "errorMessage": "Redemption failed: Max redemption limit ... per period ... has been exceeded" } ] } }, "requestBodies": { "refundPayload": { "description": "JSON Payload", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "originalTransaction", "basket", "reference" ], "properties": { "reference": { "type": "string", "format": "string", "description": "Refund Transaction Reference" }, "originalTransaction": { "type": "object", "required": [ "reference" ], "properties": { "reference": { "type": "string", "format": "string", "description": "Settle Transaction Reference" } } }, "basket": { "type": "object", "required": [ "type", "contents" ], "properties": { "type": { "type": "string", "enum": [ "STANDARD" ] }, "summary": { "$ref": "#/components/schemas/standardBasketSummaryEntity" }, "contents": { "$ref": "#/components/schemas/refundBasketContentsCollectionEntity" }, "payment": { "$ref": "#/components/schemas/standardPaymentEntity" } } }, "location": { "$ref": "#/components/schemas/locationEntity" } } } } } } }, "parameters": { "httpContentTypeRequest": { "name": "Content-Type", "in": "header", "required": false, "description": "Standard HTTP header to inform EES API what type of content was passed in request payload", "schema": { "type": "string", "format": "string", "default": "application/json" }, "allowEmptyValue": false }, "eesDateTimeOverride": { "name": "X-POSCONNECT-TRANSACTION-DATETIME", "in": "header", "required": false, "description": "The ability to specify the date and time that should be used to adjudicate. This can be used to create transactions for past events, whilst ensuring the consumer receives the rewards that they were eligible for at that time. This functionality is only available for events less than 6 months in the past. Please note requested transaction date-time has to use ATOM Date-Time format Y-m-d\\TH:i:sP, (e.g. 2017-12-31T23:59:59+09:00).", "schema": { "type": "string", "format": "eesDateTime", "nullable": false, "pattern": "^((((19|[2-9]\\d)(0[48]|[2468][048]|[13579][26])|(([2468][048]|[3579][26])00))\\-02\\-29|((19\\d{2}|[2-9]\\d{3})\\-((0[13578]|1[02])\\-31))|((19\\d{2}|[2-9]\\d{3})\\-(0[13-9]|1[0-2])\\-(29|30))|((19\\d{2}|[2-9]\\d{3})\\-(0[1-9]|1[0-2])\\-(0[1-9]|1[0-9]|2[0-8])))\\T([01][0-9]\\:[0-5][0-9]\\:[0-5][0-9]|2[0-3]\\:[0-5][0-9]\\:[0-5][0-9]))(\\+|\\-)([01][0-9]\\:[0-5][0-9]|2[0-3]\\:[0-5][0-9])$" }, "allowEmptyValue": false }, "httpAcceptEncodingRequest": { "name": "Accept-Encoding", "in": "header", "required": false, "description": "This request HTTP header advertises which content encoding (usually a compression algorithm) the calling application is able to understand. The server selects one of the proposals, use it and informs the client of its choice with the `Content-Encoding` Response header. Currently supported `gzip` and `deflate`. Please note if this request header is not present, no compression will be used.", "schema": { "type": "string", "default": "''", "enum": [ "''", "'gzip'", "'deflate'", "'gzip,deflate'", "'deflate,gzip'" ] }, "allowEmptyValue": true }, "httpMethodOverride": { "name": "X-HTTP-Method-Override", "in": "header", "required": false, "description": "Optional HTTP header, if present, it will instruct EES AIR to override the real HTTP Method, used during this connection. This is due to some networking or software limitations on Client side, allowing the calling application to perform only `GET` or `POST` calls.", "schema": { "type": "string", "enum": [ "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] }, "allowEmptyValue": false }, "httpConnectionRequest": { "name": "Connection", "in": "header", "required": false, "description": "This general HTTP header controls (or rather influences) whether the network connection stays open after the current request finishes. If the sent value is `keep-alive`, the connection should stay in a special state, allowing to be reused for subsequent requests to the same server. Please note these connections will be closed after reaching timeout threshold controlled by EES server (usually after 5 seconds).", "schema": { "type": "string", "enum": [ "keep-alive", "close" ], "default": "close" } }, "eesAuthenticationClientId": { "name": "X-EES-AUTH-CLIENT-ID", "in": "header", "description": "Client ID, provided by EES during on-boarding. Please note: the authentication mechanic requires the receipt of the full payload so any headers that would chunk the request up, such as `transfer-encoding: chunked` could potentially cause authentication failures.", "required": true, "schema": { "type": "string", "format": "string" } }, "eesAuthenticationRequestHash": { "name": "X-EES-AUTH-HASH", "in": "header", "description": "Request Authentication Hash, calculated by concatenating Request URI Path with API prefix, Request Query String(s) if applicable, Request Payload if applicable and Client Secret. Please note: the authentication mechanic requires the receipt of the full payload so any headers that would chunk the request up, such as `transfer-encoding: chunked` could potentially cause authentication failures.", "required": true, "schema": { "type": "string", "format": "string" } }, "eesMessageId": { "name": "X-EES-TRANSACTION-ID", "in": "header", "description": "Optional Unique Reference for the API Request (Transaction) within the calling company", "required": false, "schema": { "type": "string", "format": "string" } }, "customSubsystemId": { "name": "X-CUSTOM-SUBSYSTEM-ID", "in": "header", "description": "Optional header provided by the calling application for EES AIR to identify what was the external Subsystem ID / Name. Please note this header is not essential for AIR to process a Request, this header and its value will be intercepted by AIR and will show up in Wallet Event Notifications, if applicable.", "required": false, "schema": { "type": "string", "format": "string" } }, "customWildCard": { "name": "X-CUSTOM-KEY", "in": "header", "description": "Optional header(s) provided by the calling application to EES AIR. Please note a) this header name has to follow pattern X-CUSTOM-* (i.e. X-CUSTOM-EMAIL) b) this header is not essential for AIR to process a Request, this header and its value will be intercepted by AIR and will show up in Wallet Event Notifications, if applicable.\n", "required": false, "schema": { "type": "string", "format": "string" } } }, "responses": { "200refundResponsePayload": { "description": "EES AIR has successfully processed a Request", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tiersEnabledWalletAndAccountTransactionResponse" } } } }, "207refundResponsePayload": { "description": "EES AIR has processed a partially successful Request", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tiersEnabledWalletAndAccountTransactionResponse" } } } }, "error400Response": { "description": "EES AIR Refuse to process that particular Request as there is something wrong with the Request (e.g. missing Mandatory Request parameter or Mandatory Request Payload attribute is missing, Request payload is unprocessable, etc)", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/defaultErrorEntity" } ] } } } }, "error401Response": { "description": "EES AIR Refuse to process that particular Request due to Authentication error. This could be caused by missing mandatory AUTH header(s), invalid Hash calculation, invalid or inactive API Key used, etc.", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/defaultErrorEntity" } ] } } } }, "error403Response": { "description": "EES AIR Refuse to process that particular Request due to Request Authorization error(s). This indicates that used API Key has not got required permissions to perform this operation.", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/defaultErrorEntity" } ] } } } }, "error404Response": { "description": "EES AIR Refuse to process that particular Request as requested/referenced resource could not be found.", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/defaultErrorEntity" } ] } } } }, "error409Response": { "description": "EES AIR understands this request, but refuses to process it, due to present Conflict with the current state of the target resource or because performing this operation would lead to a Conflict within AIR.", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/defaultErrorEntity" } ] } } } }, "error415Response": { "description": "EES AIR is not able to understand that request due to not supported `Content-Type` value.", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/defaultErrorEntity" } ] } } } }, "error429Response": { "description": "EES AIR refuses to process that particular Request as Client's API Requests Limit was exceeded.", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/defaultErrorEntity" } ] } } } }, "error500Response": { "description": "EES AIR refuses to process that particular Request due to Unexpected Server Error.", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/defaultErrorEntity" } ] } } } }, "error503Response": { "description": "EES AIR refuses to process that particular Request due to Service(s) being Unavailable (i.e. Scheduled Maintenance)", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/defaultErrorEntity" } ] } } } }, "error504Response": { "description": "EES AIR refuses to process that particular Request due to Networking Issues", "headers": { "X-EES-TRANSACTION-ID-RESULT": { "$ref": "#/components/headers/uniquenessCheckResult" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/defaultErrorEntity" } ] } } } } }, "headers": { "uniquenessCheckResult": { "required": false, "description": "If Request Uniqueness checking is enabled for a Client, this Header will contain details regarding Request uniqueness check performed within EES AIR. `PASSED` means it was checked and a Request is unique, `FAILED` means check was performed and it fails, `UNABLE TO CHECK` means EES AIR was not able to perform uniqueness check.", "schema": { "type": "string", "nullable": false, "enum": [ "PASSED", "FAILED", "UNABLE TO CHECK" ] } } }, "securitySchemes": { "eesAuthClientId": { "type": "apiKey", "in": "header", "description": "Client ID, provided during onboarding to each EES AIR Client. Please note: API Key consist of `Client ID` and `Client Secret` required for calculating Authentication Hash (`X-EES-AUTH-HASH`). Each Unit from the Client Hierarchy can have one or more API Key(s).", "name": "X-EES-AUTH-CLIENT-ID" }, "eesAuthHash": { "type": "apiKey", "in": "header", "description": "Request Authentication Hash, obtained by concatenating Full Request URI Path (with API prefix), Request Query String(s) (if applicable), Request Payload (if applicable), Client Secret and then calculating SHA256 from this concatenated string.", "name": "X-EES-AUTH-HASH" } } }, "security": [ { "eesAuthClientId": [], "eesAuthHash": [] } ] } ```