---
title: "Retail Order"
method: POST
path: "/order/retail"
tags: ["Order"]
---

# Retail Order

`POST /order/retail`

This method allows the calling application to create Gift Voucher or plastic card Order

## Query parameters

- `include` string[]

## Headers

- `X-EES-AUTH-CLIENT-ID` string, string, required
- `X-EES-AUTH-HASH` string, string, required
- `Connection` 'close' | 'keep-alive'
- `Accept-Encoding` '' | 'gzip' | 'deflate' | 'gzip,deflate'
- `X-EES-TRANSACTION-ID` string, string
- `X-EES-RETRY` string, string
- `X-CUSTOM-SUBSYSTEM-ID` string, string
- `X-CUSTOM-KEY` string, string

## Request body

- TokenOrderRetailPayload
  - `reference` string — External reference to this order.
  - `purchaser` PurchaserEntity
    - `title` string — Title of the purchaser
    - `firstName` string — First name of the purchaser
    - `secondName` string — Second name of the purchaser
    - `phone` string — [Optional] Phone number of the purchaser
    - `emailAddress` string — Email address of the purchaser
    - `marketing` boolean — Boolean Flag to inform EES AIR if the Customer agreed to receive Marketing information, if unsure please use false
    - `purchaserAddresses` object[]
      - `line1` string — [Optional] Purchaser's first line of address
      - `line2` string — [Optional] Purchaser's second line of address
      - `line3` string — [Optional] Purchaser's third line of address
      - `line4` string — [Optional] Purchaser's fourth line of address
      - `city` string — [Optional] Purchaser's City name
      - `county` string — [Optional] Purchaser's County name
      - `postcode` string — [Optional] The purchaser's postcode
      - `country` string — [Optional] Purchaser's Country
  - `tracking` string — [Optional] The tracking reference, if tracking has been used by the calling application
  - `items` object[]
    - `programmeId` integer
    - `amount` integer
    - `delivery` object
      - `type` 'SMS' | 'EMAIL' — delivery method
      - `identity` string — Mobile number or Email value
      - `scheduled` string, date-time — Requested delivery of Test message or Email
      - `template` object
        - `templateId` integer — Id of the template, from EES AIR, to be used to delivery message
        - `content` object — Template Variable Values
          - `TO` string — Recipient Friendly name, this value will be used in the referenced template
          - `FROM` string — Sender Friendly name, this value will be used in the referenced template
          - `CUSTOM` string — SMS or Email subject
    - `discount` integer — Discount Value
    - `total` integer — Total Value
    - `meta` MetaEntity
      - `key1` string — Meta 1 property, up to 250 characters; up to 750 characters for Key 1 Value
      - `key2` string — Meta 2 property, up to 250 characters; up to 750 characters for Key 2 Value
  - `orderTotals` object
    - `voucherTotal` integer — The total value of vouchers or plastic cards in the order
    - `deliveryTotal` integer — The amount charged to the purchaser for delivering this order. Only required where there are one or more plastic cards in the order
    - `cardCharge` integer — An amount added to the order for card processing fees
    - `discountTotal` integer — The total discount being applied to this order
    - `grandTotal` integer — The total the customer is being charged for this order
  - `payment` object
    - `token` object
      - `type` 'ONCE' | 'RECURRING' — Payment Type
      - `value` string — The "tokenised" card details
      - `deviceData` string — The device data string
    - `amount` string — The amount of money to take. Normally will be the same as the 'chargeTotal' amount
  - `meta` MetaEntity
    - `key1` string — Meta 1 property, up to 250 characters; up to 750 characters for Key 1 Value
    - `key2` string — Meta 2 property, up to 250 characters; up to 750 characters for Key 2 Value

## Response `200`

Created

- TokenOrderRetailEntity
  - `orderId` integer — EES AIR Order ID
  - `unitId` integer — EES AIR Unit ID
  - `creatorId` integer — EES AIR Creator ID
  - `consumerId` integer — EES AIR Consumer ID
  - `reference` string — Requested Order Reference
  - `tracking` string — Requested External tracking value
  - `status` 'COMPLETE' | 'AWAITING_FULFILMENT' | 'FAILED' — EES AIR Order Status
  - `purchaserId` integer — EES AIR Order Purchaser ID
  - `purchaser` object
    - `purchaserId` integer — EES AIR Order Purchaser ID
    - `unitId` integer — EES AIR Unit ID
    - `title` string — [Optional] Requested Purchaser's Title
    - `firstName` string — [Optional] Requested Purchaser's First Name
    - `secondName` string — [Optional] Requested Purchaser's Last Name
    - `phone` string — [Optional] Requested Purchaser's Phone number
    - `emailAddress` string — [Optional] Requested Purchaser's Email address
    - `marketing` string — Requested value of Purchaser's Marketing flag
    - `reference` string — [Optional] Requested Purchaser's external system reference
    - `purcharserAddresses` object[]
      - `purcharserAddressId` integer — EES AIR Purchaser Address ID
      - `purchaserId` integer — EES AIR Purchaser ID
      - `line1` string — [Optional] Purchaser's first line of address
      - `line2` string — [Optional] Purchaser's second line of address
      - `line3` string — [Optional] Purchaser's third line of address
      - `line4` string — [Optional] Purchaser's fourth line of address
      - `city` string — [Optional] Purchaser's City name
      - `county` string — [Optional] Purchaser's County name
      - `postcode` string — [Optional] The purchaser's postcode
      - `country` string — [Optional] Purchaser's Country
  - `dateCreated` string, date-time — Order Creation date-time
  - `lastUpdated` string, date-time — Order last update date-time
  - `items` object[]
    - `itemId` integer — EES AIR Order Item ID
    - `orderId` integer — EES AIR Order ID
    - `programmeId` integer — EES AIR Campaign ID
    - `consumerId` integer — EES AIR Consumer ID
    - `quantity` integer — Requested Items quantity
    - `statusId` integer — EES AIR Order Status ID
    - `status` 'COMPLETE' | 'AWAITING_FULFILMENT' | 'FAILED' — EES AIR Order Status
    - `deliveryId` integer — EES AIR Delivery ID
    - `delivery` object
      - `deliveryId` integer — EES AIR Delivery ID
      - `accountId` integer — EES AIR Account ID
      - `deliveryType` string — Delivery type (e.g. POSTAL)
      - `templateId` integer — EES AIR Template ID
      - `content` object
        - `address` object
          - `firstName` string — [Optional] Purchaser's First Name
          - `lastName` string — [Optional] Purchaser's Last Name
          - `line1` string — [Optional] Purchaser's first line of address
          - `line2` string — [Optional] Purchaser's second line of address
          - `line3` string — [Optional] Purchaser's third line of address
          - `line4` string — [Optional] Purchaser's fourth line of address
          - `city` string — [Optional] Purchaser's City name
          - `county` string — [Optional] Purchaser's County name
          - `postcode` string — [Optional] The purchaser's postcode
          - `country` string — [Optional] Purchaser's Country
        - `type` string — Delivery Type (e.g. POSTAL)
        - `identity` string — Identity value
        - `template` object
          - `templateId` integer — EES AIR Template ID
          - `content` object
            - `address` string — Template Value
            - `TO` string — Template Value
            - `FROM` string — Template Value
            - `CUSTOM` string — Template Value
            - `amount` string — Template Value
    - `value` integer — Single Coupon / Plastic Value
    - `total` integer — Order Item Total Value
    - `discountTotal` integer — Order Item Discount Total
    - `meta` MetaEntity
      - `key1` string — Meta 1 property, up to 250 characters; up to 750 characters for Key 1 Value
      - `key2` string — Meta 2 property, up to 250 characters; up to 750 characters for Key 2 Value
    - `accounts` WalletAccountEntity[] — Array of account entities.
      - `accountId` string, required — EES AIR Wallet Account ID
      - `relationships` object — Wallet Accounts Relations
        - `ENTITLEMENT` object
          - `accountType` WalletAccountRelationEntity
            - `accountId` string, int64, required — Account ID
            - `dateCreated` string, date-time, required — Relation creation date-time
        - `ENTITLEMENT_OF` object
          - `accountType` WalletAccountRelationEntity
            - `accountId` string, int64, required — Account ID
            - `dateCreated` string, date-time, required — Relation creation date-time
      - `walletId` string, required — EES AIR Wallet ID
      - `campaignId` string, required — The campaignId (Campaign or Programme) this account belongs to.
      - `type` 'ECOUPON' | 'VOUCHER' | 'PAPER' | 'DEBIT' | 'PLASTIC', required — EES AIR Account Type.
      - `clientType` string, required — Account client type.
      - `status` 'ACTIVE' | 'BLOCKED' | 'CANCELLED' | 'DELETED' | 'EXPIRED' | 'INACTIVE' | 'INVALIDATED' | 'LOCKED' | 'STOLEN' | 'USED', required — Account status
      - `state` string, required — Account state, managed per retailer base, list of possible enum values could be set-up as part of the Onboarding process.
      - `dates` DatesEntity, required
        - `start` string, date-time
        - `end` string, date-time
      - `meta` MetaEntity, required
        - `key1` string — Meta 1 property, up to 250 characters; up to 750 characters for Key 1 Value
        - `key2` string — Meta 2 property, up to 250 characters; up to 750 characters for Key 2 Value
      - `balances` AccountBalancesEntity, required — The object of balances. Some balances only apply to certain types of accounts. See notes below on balances.
        - `available` integer — 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.
        - `refundable` integer — 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.
        - `totalSpend` integer — The total spend balance. Applicable only to CONTINUITY type Accounts. If totalSpend is not provided on creation, this will be set to 0.
        - `transactionCount` integer — The transaction counter. Applicable only to CONTINUITY type Accounts. If transactionCount is not provided on creation, this will be set to 0.
        - `current` integer — The current balance. Applicable only to accounts of type POINTS and STAMP. If not provided on creation, this will be set to 0.
        - `usable` integer — The usable balance. Applicable only to accounts of type POINTS. If not provided on creation, this will be set to 0.
        - `locked` integer — The locked balance. Applicable only to accounts of type POINTS. If not provided on creation, this will be set to 0.
        - `lifetime` integer — The lifetime balance. Applicable only to accounts of type POINTS and STAMP. If not provided on creation, this will be set to 0.
      - `dateCreated` string, date-time, required — Date this Account was created
      - `lastUpdated` string, date-time, required — Date this Account was last updated
      - `tokens` TokenEntity[] — Array of token entities, present only if include=tokens is passed in the query string.
        - `tokenId` string — The Token ID.
        - `accountId` string — The Account ID.
        - `token` string — The Token.
        - `validFrom` string, date-time — The date this token is valid from.
        - `validTo` string, date-time — The date this token is valid to.
        - `dateCreated` string, date-time — The date this token was created.
        - `lastUpdated` string, date-time — The date this token was last updated.
        - `status` string — The status of the Token.
        - `tokenLock` object — Token lock information. All values can be null if no token lock exists.
          - `validFrom` string, date-time — The date the token lock is valid from.
          - `validTo` string, date-time — The date the token lock is valid to.
    - `dateCreated` string, date-time — EES AIR Item Creation Date-Time
    - `lastUpdated` string, date-time — EES AIR Item Last Updated Date-Time
  - `payment` object — [Optional] Payment Object
    - `paymentId` integer — EES AIR Payment ID
    - `amount` integer — Payment Amount denominated in smallest currency unit (for GBP this should be in pence)
  - `orderTotals` object
    - `voucherTotal` integer — Voucher Total
    - `deliveryTotal` integer — Delivery Total
    - `cardCharge` integer — Card Charge
    - `discountTotal` integer — Discount Total
    - `grandTotal` integer — Grand Total

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `415` — Unsupported Media Type
- `429` — Too Many Requests
- `500` — Server Error
- `503` — Service Unavailable
- `504` — Gateway Timeout

---

[API](https://skmtc.net/eagleeye/apis/wallet-api.md) · [All operations](https://skmtc.net/eagleeye/apis/wallet-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/eagleeye/wallet-api/revisions/90a122bb14cc/schema)