--- title: Schema Reference slug: devdocs/schema-reference docTags: createdAt: 2026-10-16T12:03:52.197Z --- This page lists the customer and loyalty part of the schema. The CRM & Loyalty API and the Delivery API share one schema. For the rest, see the **Schema Reference** of the Delivery API. ## Entry points | Entry point | What it gives you | | ------------------------------ | ------------------------------------------------------------------------------ | | `customers.customer` | Customers, with their addresses, companies, marketing actions and loyalty data | | `customers.customerCategories` | The active customer categories | | `loyalty.promotion` | The loyalty promotions | | `order.orders` | Orders and receipts, with the points of each receipt | | `organization` | Reference data: organizations, currencies, VAT categories, marketing actions | | `errorCodes` | The catalogue of error codes of the mutations | ## Types ### Customer (`CustomerType`) | Field | Type | Description | | ---------------------- | ------------------------------- | ------------------------------------------------------------------------------------------ | | `publicKey` | `Guid!` | | | `firstName` | `String!` | Customer first name. | | `lastName` | `String!` | Customer last name. | | `active` | `Boolean!` | Indicates if the customer is active. | | `code(windowMinutes)` | `String` | Customer code/reference. Pass windowMinutes for a time-limited HMAC token safe for QR use. | | `email` | `String` | Email address from contact extension. | | `mobilePhone` | `String` | Mobile phone from contact extension. | | `workPhone` | `String` | Work phone from contact extension. | | `homePhone` | `String` | Home phone from contact extension. | | `birthDate` | `DateTime` | Customer date of birth from contact extension. | | `category` | `CustomerCategoryType` | Customer category reference. | | `segmentationCategory` | `SegmentationCategoryType` | Customer segmentation category from contact extension. | | `addresses(publicKey)` | `[CustomerAddressType]` | Customer addresses. Optional filter by address public key. | | `companies` | `[CustomerCompanyType]` | Companies linked to this customer (B2B associations). | | `marketingActions` | `[CustomerMarketingActionType]` | Marketing actions assigned to this customer. | | `loyalty` | `CustomerLoyaltyQuery` | Customer loyalty info (balances, wallets, operations). | ### Customer voucher (`CustomerLoyaltyVoucherType`) | Field | Type | Description | | ------------------- | --------------------- | ------------------------------------------------------------------ | | `voucher` | `LoyaltyVoucherType!` | Voucher definition linked to the customer. | | `maximumUsageCount` | `Int` | Maximum usage count (overrides voucher default if set on mapping). | | `usedCount` | `Int` | How many times the customer used this voucher. | ### Voucher (`LoyaltyVoucherType`) | Field | Type | Description | | --------------------- | ----------------------------- | ---------------------------------------------------------------------------------------- | | `publicKey` | `Guid!` | | | `name` | `String!` | Voucher name. | | `code(windowMinutes)` | `String` | Voucher external code. Pass windowMinutes for a time-limited HMAC token safe for QR use. | | `maximumUsageCount` | `Int` | Maximum usage count; null/0 means unlimited. | | `beginDate` | `Date!` | validity period starting from | | `endDate` | `Date!` | validity period end moment | | `isActive` | `Boolean!` | Indicates if voucher is active. | | `discountType` | `DiscountType!` | Discount type (percentage or amount). | | `discountValue` | `Decimal!` | Discount value according to discount type. | | `currency` | `CurrencyType` | Currency for discount value. | | `locations` | `[LocationType]` | locations where the voucher can be used | | `products` | `[LoyaltyVoucherProductType]` | Products where the voucher applies (if restricted). | ### Voucher product rule (`LoyaltyVoucherProductType`) | Field | Type | Description | | --------------- | -------------- | --------------------------------------------------------------------- | | `publicKey` | `Guid!` | | | `product` | `ProductType!` | Product to which the voucher applies. | | `quantity` | `Decimal!` | Quantity covered by the voucher. | | `discountType` | `DiscountType` | Discount type for this product rule (null if no discount). | | `discountValue` | `Decimal` | Discount value for this product rule. | | `salePrice` | `Decimal` | Sale price with VAT defined by the voucher for this product (if any). | ### Promotion (`LoyaltyPromotionType`) | Field | Type | Description | | --------------- | --------------- | ----------------------------------------------- | | `publicKey` | `Guid!` | | | `name` | `String` | Promotion name. | | `active` | `Boolean` | Indicates if the promotion is active. | | `promotionType` | `PromotionType` | Promotion type enum. | | `weekDay` | `Byte` | Weekday flags (bitwise) when promotion applies. | | `beginDate` | `Date` | Validity start date. | | `endDate` | `Date` | Validity end date. | ### Receipt (`OrderReceiptType`) | Field | Type | Description | | ---------------- | ------------------------- | ----------- | | `publicKey` | `Guid!` | | | `createdOn` | `DateTime!` | | | `number` | `Int!` | | | `products` | `[OrderProductType]` | | | `paymentMethods` | `[OrderPaymentItemType]` | | | `loyalty` | `OrderReceiptLoyaltyType` | | ### Receipt points (`OrderReceiptLoyaltyPointsType`) | Field | Type | Description | | -------- | --------- | ----------- | | `credit` | `Decimal` | | | `debit` | `Decimal` | | ### Gift card (`GiftCardType`) | Field | Type | Description | | -------------- | ---------------------- | ----------- | | `publicKey` | `Guid!` | | | `organization` | `OrganizationBaseType` | | | `amount` | `Decimal!` | | | `vatCategory` | `VATCategoryType` | | | `currency` | `CurrencyType` | | | `code` | `String` | | | `name` | `String` | | | `startOn` | `DateTime!` | | | `expireOn` | `DateTime!` | | ## Mutations Every mutation returns `result`, `errorCode`, `errorMessage` and `errorData`. | Mutation | Argument | Returns | | --------------------------------- | ---------------------------------------------- | --------------------------- | | `customer.create` | `payload: CustomerCreateInputType!` | `CustomerTypeResult` | | `customer.update` | `payload: CustomerUpdateInputType!` | `CustomerTypeResult` | | `customer.delete` | `payload: Guid!` | `BooleanGraphTypeResult` | | `customer.createAddress` | `payload: CustomerAddressCreateInputType!` | `CustomerAddressTypeResult` | | `customer.updateCustomerAddress` | `payload: CustomerAddressUpdateInputType!` | `CustomerAddressTypeResult` | | `customer.deleteAddress` | `payload: Guid!` | `BooleanGraphTypeResult` | | `customer.linkCompany` | `payload: CustomerCompanyLinkInputType!` | `CustomerTypeResult` | | `customer.unlinkCompany` | `payload: CustomerCompanyLinkInputType!` | `CustomerTypeResult` | | `customer.upsertMarketingActions` | `payload: [CustomerMarketingActionInputType]!` | `BooleanGraphTypeResult` | | `organization.createGiftCard` | `payload: CreateGiftCardInputType!` | `GiftCardTypeResult` | ## Input types ### CustomerCreateInputType | Field | Type | Required | Default | Description | | ------------- | ---------- | -------- | ------- | ---------------------------------- | | `category` | `Guid!` | yes | | Customer category key. | | `firstName` | `String!` | yes | | Customer first name. | | `lastName` | `String!` | yes | | Customer last name. | | `code` | `String` | no | | Customer code/reference. | | `email` | `String` | no | | Customer email. | | `mobilePhone` | `String!` | yes | | Mobile phone (mandatory). | | `workPhone` | `String` | no | | Work phone. | | `homePhone` | `String` | no | | Home phone. | | `birthDate` | `DateTime` | no | | Customer date of birth (optional). | ### CustomerUpdateInputType | Field | Type | Required | Default | Description | | ------------- | ---------- | -------- | ---------------------------------------- | ----------------------------------- | | `publicKey` | `Guid!` | yes | | Customer public key. | | `category` | `Guid` | no | `"00000000-0000-0000-0000-000000000000"` | Customer category key (optional). | | `firstName` | `String` | no | `" "` | Customer first name (optional). | | `lastName` | `String` | no | `" "` | Customer last name (optional). | | `code` | `String` | no | `" "` | Customer code/reference (optional). | | `email` | `String` | no | `" "` | Customer email (optional). | | `mobilePhone` | `String` | no | `" "` | Mobile phone (optional). | | `workPhone` | `String` | no | `" "` | Work phone (optional). | | `homePhone` | `String` | no | `" "` | Home phone (optional). | | `birthDate` | `DateTime` | no | `"0001-01-01T00:00:00"` | Customer date of birth (optional). | ### CustomerAddressCreateInputType | Field | Type | Required | Default | Description | | ---------------- | ---------------------- | -------- | ------- | ------------------------------- | | `customerKey` | `Guid!` | yes | | Customer public key. | | `streetKey` | `Guid!` | yes | | Street public key. | | `streetNumber` | `String` | no | | Street number (free-text). | | `buildingNumber` | `String` | no | | Building number/identifier. | | `staircase` | `String` | no | | Staircase/entrance identifier. | | `floor` | `String` | no | | Floor information. | | `roomNumber` | `String` | no | | Room/apartment number. | | `intercom` | `String` | no | | Intercom code. | | `landmark` | `String` | no | | Landmark near the address. | | `geoLocation` | `GeoLocationInputType` | no | | Latitude/Longitude coordinates. | ### CustomerAddressUpdateInputType | Field | Type | Required | Default | Description | | ---------------- | ---------------------- | -------- | ---------------------------------------- | ------------------------------- | | `publicKey` | `Guid!` | yes | | Address public key. | | `streetKey` | `Guid` | no | `"00000000-0000-0000-0000-000000000000"` | Street public key (optional). | | `streetNumber` | `String` | no | `" "` | Street number (optional). | | `buildingNumber` | `String` | no | `" "` | Building number (optional). | | `staircase` | `String` | no | `" "` | Staircase (optional). | | `floor` | `String` | no | `" "` | Floor (optional). | | `roomNumber` | `String` | no | `" "` | Room number (optional). | | `intercom` | `String` | no | `" "` | Intercom (optional). | | `landmark` | `String` | no | `" "` | Landmark (optional). | | `geoLocation` | `GeoLocationInputType` | no | | Latitude/Longitude coordinates. | ### GeoLocationInputType | Field | Type | Required | Default | Description | | ----- | -------- | -------- | ------- | ----------- | | `lat` | `Float!` | yes | | | | `lng` | `Float!` | yes | | | ### CustomerCompanyLinkInputType | Field | Type | Required | Default | Description | | ------------- | ------- | -------- | ------- | -------------------- | | `customerKey` | `Guid!` | yes | | Customer public key. | | `companyKey` | `Guid!` | yes | | Company public key. | ### CustomerMarketingActionInputType | Field | Type | Required | Default | Description | | -------------------- | ---------- | -------- | ------- | --------------------------------------------------- | | `customerKey` | `Guid!` | yes | | Customer public key. | | `marketingActionKey` | `Guid!` | yes | | Marketing action public key. | | `value` | `Boolean!` | yes | | Action flag value (opt-in = true, opt-out = false). | ### CreateGiftCardInputType | Field | Type | Required | Default | Description | | ----------------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------ | | `organizationKey` | `Guid!` | yes | | Organization that owns the gift card. | | `amount` | `Decimal!` | yes | | Gift card face value (TotalAmountWithVAT). | | `vatCategoryKey` | `Guid!` | yes | | VAT category applied to the gift card amount. | | `currencyKey` | `Guid!` | yes | | Currency of the gift card amount. | | `code` | `String` | no | | External code (max 8 alphanumeric). Generated randomly if omitted. | | `name` | `String` | no | | Gift card display name/title, shown in CRM. Falls back to the code if omitted. | | `startOn` | `DateTime!` | yes | | Validity start date (non-UTC, as stored). | | `expireOn` | `DateTime!` | yes | | Expiry date (non-UTC, as stored). | ## Enum values | Enum | Values | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DiscountType` | `PERCENT`, `AMOUNT` | | `PromotionType` | `PRODUCT_DISCOUNT`, `PRODUCT_SALE_PRICE`, `CUSTOMER_DISCOUNT`, `BUY_X_GET_Y`, `BUY_X_AND_Y_GET_DISCOUNT`, `BUY_X_GET_Y_FREE_LOWEST_PRICE_ITEM`, `BUY_PRODUCT_COMBINATION_GET_SPECIAL_PRICES`, `CUSTOMER_DISCOUNT_ON_PAYMENT_METHOD`, `BUY_CERTAIN_VALUE_GET_PRODUCTS_WITH_DISCOUNTS_OR_SPECIAL_PRICES`, `COMPANY_DISCOUNT` | | `CustomerConnnectionOrderType` | `FIRST_NAME`, `FIRST_NAME_DESC`, `LAST_NAME`, `LAST_NAME_DESC` | | `PromotionConnnectionOrderType` | `NAME`, `NAME_DESC` | | `OrderConnnectionOrderType` | `CREATED_ON`, `CREATED_ON_DESC` |