Schema Reference

20 min

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	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	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	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	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