> For the complete documentation index, see [llms.txt](https://docs.hos.accessacloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hos.accessacloud.com/atreemo-api/api-reference/atreemo-api-reference/voucher.md). # Voucher Api Methods for Voucher ## ConfirmRedeemVoucher > Confirm the voucher redemption (RedemptionID should be retrieved from the method ValidateVoucher) ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"BenefitRedemptionInput":{"type":"object","properties":{"CustomerID":{"type":"integer","format":"int32","nullable":true,"description":"The ID of the customer (CtcID)"},"RedemptionID":{"type":"string","description":"The ID of the redemption to confirm"}}},"BenefitRedemptionOutput":{"type":"object","properties":{"Error":{"type":"array","items":{"type":"string"},"description":"The list of errors description"},"Response":{"type":"boolean","description":"The status of the call"}}}}},"paths":{"/api/Voucher/ConfirmRedeemVoucher":{"post":{"operationId":"VoucherConfirmRedeemVoucher","summary":"ConfirmRedeemVoucher","tags":["Voucher"],"description":"Confirm the voucher redemption (RedemptionID should be retrieved from the method ValidateVoucher)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitRedemptionInput"}}}},"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitRedemptionOutput"}}}}}}}}} ``` ## Create > Create a voucher code for a known customer ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"CreateVoucherInput":{"type":"object","properties":{"SourceID":{"type":"string","description":"The source of creation"}}},"CreateVoucherOutput":{"type":"object","properties":{"Error":{"type":"array","items":{"type":"string"},"description":"The list of errors description"},"Response":{"type":"boolean","description":"The status of the call"},"VoucherCode":{"type":"string","description":"The code of the voucher"},"VoucherExpiryDate":{"type":"string","format":"date-time","description":"The end date time of the voucher"},"VoucherPrefix":{"type":"string","description":"the first part of voucher code (offercode)"},"VoucherStartDate":{"type":"string","format":"date-time","description":"The start date time of the voucher"},"VoucherSuffix":{"type":"string","description":"last last part voucher code (without offer code)"},"VoucherValue":{"type":"number","format":"double","description":"The value of the voucher"}}}}},"paths":{"/api/Voucher/Create":{"post":{"operationId":"VoucherCreate","summary":"Create","tags":["Voucher"],"description":"Create a voucher code for a known customer","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVoucherInput"}}}},"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVoucherOutput"}}}}}}}}} ``` ## DeactivateVouchers > Deactivate Vouchers ( max 100 voucher code per call ) ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"ApiCallResponse":{"type":"object","properties":{"Errors":{"type":"array","items":{"$ref":"#/components/schemas/APICallError"},"description":"Collection of errors if exist"},"ResponseStatus":{"type":"boolean","description":"True: if the action was succsessfully treated False: if there is an error"}}},"APICallError":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32","description":"The error code"},"ErrorDescription":{"type":"string","description":"The error description"}}}}},"paths":{"/api/Voucher/DeactivateVouchers":{"patch":{"operationId":"VoucherDeactivateVouchers","summary":"DeactivateVouchers","tags":["Voucher"],"description":"Deactivate Vouchers ( max 100 voucher code per call )","requestBody":{"content":{"application/json":{"schema":{"description":"Request body structure is not documented in the public collection."}}}},"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCallResponse"}}}}}}}}} ``` ## Get > Get voucher details by voucher code ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"GetVoucherOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"response":{"type":"boolean","description":"Status of the call"},"voucher":{"allOf":[{"$ref":"#/components/schemas/Voucher"}],"description":"Voucher details"}}},"Voucher":{"type":"object","properties":{"CategoryID":{"type":"integer","format":"int32","description":"Voucher category ID"},"CategoryName":{"type":"string","description":"Voucher category name"},"Conditions":{"type":"string","description":"Terms and condition (text format)"},"CtcID":{"type":"integer","format":"int32","nullable":true,"description":"Customer id linked to this voucher"},"CtcUID":{"type":"string","description":"Customer unique id linked to this voucher"},"CustomerName":{"type":"string","description":"Customer name linked to this voucher"},"DaypartID":{"type":"integer","format":"int32","nullable":true,"description":"Used to get the predefined Schedules and Locations"},"Description":{"type":"string","description":"Voucher short description"},"Disabled":{"type":"boolean","description":"Voucher status (Disabled or not)"},"DiscountAmount":{"type":"number","format":"double","description":"Discount amount in £ (5 mean 5£)"},"DiscountPercentage":{"type":"number","format":"double","description":"Discount percentage (10 mean 10%)"},"DiscountType":{"type":"string","description":"The type of the discount \"P\" or \"M\" (if DiscountType = \"P\" so you find the percentage in the field \"DiscountPercentage\" else you find the discount amount in the field \"DiscountAmount\""},"ExpiryDate":{"type":"string","format":"date-time","nullable":true,"description":"Voucher end date"},"InfiniteVoucherRedemption":{"type":"boolean","description":"Use to determine whether the Offer Voucher's can be redeemed infinitely or not"},"IssuancePointsWorth":{"type":"number","format":"double","description":"Number of loyalty points burned from customer balance when the voucher code will be issued."},"LargeImage":{"type":"string","description":"The URL of the large image if exist"},"Location":{"type":"string","description":"The redemption location (if the redemption voucher status = reddemed)"},"MaxVoucherRedemption":{"type":"integer","format":"int32","nullable":true,"description":"Used to set the Maximum number of Vouchers that can be redeemed by Period ( PeriodDaysByVoucher ) when the InfiniteVoucherRedemption is false"},"MaxVoucherRedemptionOncePerNumberOfDays":{"type":"integer","format":"int32","nullable":true,"description":"The Voucher can be redeemed Once Per mentioned number of days if the flag InfiniteVoucherRedemption is set to true or InfiniteVoucherRedemption is false and we have a MaxVoucherRedemption value"},"MediumImage":{"type":"string","description":"The URL of the medium image if exist"},"Message":{"type":"string","description":"Voucher long description (Text format)"},"Notes":{"type":"string","description":"Voucher notes"},"OfferID":{"type":"integer","format":"int32","nullable":true,"description":"Offer unique id"},"ProductKey":{"type":"string","description":"The OfferCode"},"Products":{"type":"array","items":{"type":"string"},"description":"List of product codes affected by the discount"},"QualifiedBasketAmount":{"type":"number","format":"double","description":"List of product codes. Used if the field \"VoucherTypeName\" = \"Spend\" so the basket amount must be equal or greater this amount to validate the voucher"},"QualifiedBasketProducts":{"type":"array","items":{"type":"string"},"description":"Used if the field \"VoucherTypeName\" = \"Linked Products\" so the basket must contain all these products to validate the voucher."},"RandomID":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"},"ReactivationComment":{"type":"string","description":"Reactivation Comment"},"Redeemed":{"type":"boolean","nullable":true,"description":"Voucher redemption status (redeemed or not)"},"RedeemedBy":{"type":"string","description":"The user id who has redeem the vouccher (If the redemption voucher status = Redeemed)"},"RedemptionDate":{"type":"string","format":"date-time","nullable":true,"description":"Redemption date (if the redemption voucher status = redeemed)"},"SmallImage":{"type":"string","description":"The URL of the small image if exist"},"StartDate":{"type":"string","format":"date-time","nullable":true,"description":"Voucher start date"},"SubCategoryID":{"type":"integer","format":"int32","nullable":true,"description":"Voucher sub category ID"},"SubCategoryName":{"type":"string","description":"Voucher Sub category name"},"URD":{"type":"string","format":"date-time","nullable":true,"description":"Voucher create date"},"Value":{"type":"number","format":"double","nullable":true,"description":"Value of the voucher"},"VoucherCode":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"},"VoucherID":{"type":"integer","format":"int32","nullable":true,"description":"Voucher unique id"},"VoucherTypeName":{"type":"string","description":"the type of the voucher : Cash : you find the value in the field \"Value\" Product : you find the List of product codes affected by the discount in the field \"Products\" and percentage of the discount in the field \"DiscountPercentage\" Linked Products : you find the list of products should be in the basket in the field \"QualifiedBasketProducts\" and the List of product codes affected by the discount in the field \"Products\" and percentage of the discount in the field \"DiscountPercentage\" Spend : you find the amount of the basket should be in the field \"QualifiedBasketAmount\" and the List of product codes affected by the discount in the field \"Products\" and the discount is : If the field \"DiscountType\" = \"P\" then you find the percentage of the discount in the field \"DiscountPercentage\" If the field \"DiscountType\" = \"M\" then you find the amount of the discount in the field \"DiscountAmount\""}}}}},"paths":{"/api/Voucher/Get":{"get":{"operationId":"VoucherGet","summary":"Get","tags":["Voucher"],"description":"Get voucher details by voucher code","parameters":[{"name":"vouchercode","in":"query","schema":{"type":"string","nullable":true},"description":"Native query parameter. CLR string vouchercode in the pinned controller signature.","required":true}],"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVoucherOutput"}}}}}}}}} ``` ## GetAllByCustomerID > Get list of all vouchers ( redeemed or not ) related to a customer ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"GetVoucherListOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"OfferCategories":{"type":"array","items":{"$ref":"#/components/schemas/OfferCategory"},"description":"List of Voucher categories"},"response":{"type":"boolean","description":"Status of the call"},"voucher":{"type":"array","items":{"$ref":"#/components/schemas/Voucher"},"description":"List of Voucher details"}}},"OfferCategory":{"type":"object","properties":{"CategoryImgUrl":{"type":"string","description":"Voucher category Image URL"},"CategoryOrder":{"type":"integer","format":"int32","nullable":true,"description":"Display Order"}}},"Voucher":{"type":"object","properties":{"CategoryID":{"type":"integer","format":"int32","description":"Voucher category ID"},"CategoryName":{"type":"string","description":"Voucher category name"},"Conditions":{"type":"string","description":"Terms and condition (text format)"},"CtcID":{"type":"integer","format":"int32","nullable":true,"description":"Customer id linked to this voucher"},"CtcUID":{"type":"string","description":"Customer unique id linked to this voucher"},"CustomerName":{"type":"string","description":"Customer name linked to this voucher"},"DaypartID":{"type":"integer","format":"int32","nullable":true,"description":"Used to get the predefined Schedules and Locations"},"Description":{"type":"string","description":"Voucher short description"},"Disabled":{"type":"boolean","description":"Voucher status (Disabled or not)"},"DiscountAmount":{"type":"number","format":"double","description":"Discount amount in £ (5 mean 5£)"},"DiscountPercentage":{"type":"number","format":"double","description":"Discount percentage (10 mean 10%)"},"DiscountType":{"type":"string","description":"The type of the discount \"P\" or \"M\" (if DiscountType = \"P\" so you find the percentage in the field \"DiscountPercentage\" else you find the discount amount in the field \"DiscountAmount\""},"ExpiryDate":{"type":"string","format":"date-time","nullable":true,"description":"Voucher end date"},"InfiniteVoucherRedemption":{"type":"boolean","description":"Use to determine whether the Offer Voucher's can be redeemed infinitely or not"},"IssuancePointsWorth":{"type":"number","format":"double","description":"Number of loyalty points burned from customer balance when the voucher code will be issued."},"LargeImage":{"type":"string","description":"The URL of the large image if exist"},"Location":{"type":"string","description":"The redemption location (if the redemption voucher status = reddemed)"},"MaxVoucherRedemption":{"type":"integer","format":"int32","nullable":true,"description":"Used to set the Maximum number of Vouchers that can be redeemed by Period ( PeriodDaysByVoucher ) when the InfiniteVoucherRedemption is false"},"MaxVoucherRedemptionOncePerNumberOfDays":{"type":"integer","format":"int32","nullable":true,"description":"The Voucher can be redeemed Once Per mentioned number of days if the flag InfiniteVoucherRedemption is set to true or InfiniteVoucherRedemption is false and we have a MaxVoucherRedemption value"},"MediumImage":{"type":"string","description":"The URL of the medium image if exist"},"Message":{"type":"string","description":"Voucher long description (Text format)"},"Notes":{"type":"string","description":"Voucher notes"},"OfferID":{"type":"integer","format":"int32","nullable":true,"description":"Offer unique id"},"ProductKey":{"type":"string","description":"The OfferCode"},"Products":{"type":"array","items":{"type":"string"},"description":"List of product codes affected by the discount"},"QualifiedBasketAmount":{"type":"number","format":"double","description":"List of product codes. Used if the field \"VoucherTypeName\" = \"Spend\" so the basket amount must be equal or greater this amount to validate the voucher"},"QualifiedBasketProducts":{"type":"array","items":{"type":"string"},"description":"Used if the field \"VoucherTypeName\" = \"Linked Products\" so the basket must contain all these products to validate the voucher."},"RandomID":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"},"ReactivationComment":{"type":"string","description":"Reactivation Comment"},"Redeemed":{"type":"boolean","nullable":true,"description":"Voucher redemption status (redeemed or not)"},"RedeemedBy":{"type":"string","description":"The user id who has redeem the vouccher (If the redemption voucher status = Redeemed)"},"RedemptionDate":{"type":"string","format":"date-time","nullable":true,"description":"Redemption date (if the redemption voucher status = redeemed)"},"SmallImage":{"type":"string","description":"The URL of the small image if exist"},"StartDate":{"type":"string","format":"date-time","nullable":true,"description":"Voucher start date"},"SubCategoryID":{"type":"integer","format":"int32","nullable":true,"description":"Voucher sub category ID"},"SubCategoryName":{"type":"string","description":"Voucher Sub category name"},"URD":{"type":"string","format":"date-time","nullable":true,"description":"Voucher create date"},"Value":{"type":"number","format":"double","nullable":true,"description":"Value of the voucher"},"VoucherCode":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"},"VoucherID":{"type":"integer","format":"int32","nullable":true,"description":"Voucher unique id"},"VoucherTypeName":{"type":"string","description":"the type of the voucher : Cash : you find the value in the field \"Value\" Product : you find the List of product codes affected by the discount in the field \"Products\" and percentage of the discount in the field \"DiscountPercentage\" Linked Products : you find the list of products should be in the basket in the field \"QualifiedBasketProducts\" and the List of product codes affected by the discount in the field \"Products\" and percentage of the discount in the field \"DiscountPercentage\" Spend : you find the amount of the basket should be in the field \"QualifiedBasketAmount\" and the List of product codes affected by the discount in the field \"Products\" and the discount is : If the field \"DiscountType\" = \"P\" then you find the percentage of the discount in the field \"DiscountPercentage\" If the field \"DiscountType\" = \"M\" then you find the amount of the discount in the field \"DiscountAmount\""}}}}},"paths":{"/api/Voucher/GetAllByCustomerID":{"get":{"operationId":"VoucherGetAllByCustomerId","summary":"GetAllByCustomerID","tags":["Voucher"],"description":"Get list of all vouchers ( redeemed or not ) related to a customer","parameters":[{"name":"customerid","in":"query","schema":{"type":"integer","format":"int32"},"description":"Native query parameter. CLR int customerid in the pinned controller signature.","required":true}],"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVoucherListOutput"}}}}}}}}} ``` ## GetAllByCustomerIDByParams > Retrieves vouchers through the customer/filter lookup within the caller's authorised brands. The same source action accepts GET and POST with a complex GetAllByCustomerIDByParamsInput; the public GET entry does not describe that body. Preserve the GET catalogue entry but confirm binding/intermediary behaviour before using it; do not manufacture query expansion. The documented POST variant carries the JSON input. ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"GetVoucherListOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"OfferCategories":{"type":"array","items":{"$ref":"#/components/schemas/OfferCategory"},"description":"List of Voucher categories"},"response":{"type":"boolean","description":"Status of the call"},"voucher":{"type":"array","items":{"$ref":"#/components/schemas/Voucher"},"description":"List of Voucher details"}}},"OfferCategory":{"type":"object","properties":{"CategoryImgUrl":{"type":"string","description":"Voucher category Image URL"},"CategoryOrder":{"type":"integer","format":"int32","nullable":true,"description":"Display Order"}}},"Voucher":{"type":"object","properties":{"CategoryID":{"type":"integer","format":"int32","description":"Voucher category ID"},"CategoryName":{"type":"string","description":"Voucher category name"},"Conditions":{"type":"string","description":"Terms and condition (text format)"},"CtcID":{"type":"integer","format":"int32","nullable":true,"description":"Customer id linked to this voucher"},"CtcUID":{"type":"string","description":"Customer unique id linked to this voucher"},"CustomerName":{"type":"string","description":"Customer name linked to this voucher"},"DaypartID":{"type":"integer","format":"int32","nullable":true,"description":"Used to get the predefined Schedules and Locations"},"Description":{"type":"string","description":"Voucher short description"},"Disabled":{"type":"boolean","description":"Voucher status (Disabled or not)"},"DiscountAmount":{"type":"number","format":"double","description":"Discount amount in £ (5 mean 5£)"},"DiscountPercentage":{"type":"number","format":"double","description":"Discount percentage (10 mean 10%)"},"DiscountType":{"type":"string","description":"The type of the discount \"P\" or \"M\" (if DiscountType = \"P\" so you find the percentage in the field \"DiscountPercentage\" else you find the discount amount in the field \"DiscountAmount\""},"ExpiryDate":{"type":"string","format":"date-time","nullable":true,"description":"Voucher end date"},"InfiniteVoucherRedemption":{"type":"boolean","description":"Use to determine whether the Offer Voucher's can be redeemed infinitely or not"},"IssuancePointsWorth":{"type":"number","format":"double","description":"Number of loyalty points burned from customer balance when the voucher code will be issued."},"LargeImage":{"type":"string","description":"The URL of the large image if exist"},"Location":{"type":"string","description":"The redemption location (if the redemption voucher status = reddemed)"},"MaxVoucherRedemption":{"type":"integer","format":"int32","nullable":true,"description":"Used to set the Maximum number of Vouchers that can be redeemed by Period ( PeriodDaysByVoucher ) when the InfiniteVoucherRedemption is false"},"MaxVoucherRedemptionOncePerNumberOfDays":{"type":"integer","format":"int32","nullable":true,"description":"The Voucher can be redeemed Once Per mentioned number of days if the flag InfiniteVoucherRedemption is set to true or InfiniteVoucherRedemption is false and we have a MaxVoucherRedemption value"},"MediumImage":{"type":"string","description":"The URL of the medium image if exist"},"Message":{"type":"string","description":"Voucher long description (Text format)"},"Notes":{"type":"string","description":"Voucher notes"},"OfferID":{"type":"integer","format":"int32","nullable":true,"description":"Offer unique id"},"ProductKey":{"type":"string","description":"The OfferCode"},"Products":{"type":"array","items":{"type":"string"},"description":"List of product codes affected by the discount"},"QualifiedBasketAmount":{"type":"number","format":"double","description":"List of product codes. Used if the field \"VoucherTypeName\" = \"Spend\" so the basket amount must be equal or greater this amount to validate the voucher"},"QualifiedBasketProducts":{"type":"array","items":{"type":"string"},"description":"Used if the field \"VoucherTypeName\" = \"Linked Products\" so the basket must contain all these products to validate the voucher."},"RandomID":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"},"ReactivationComment":{"type":"string","description":"Reactivation Comment"},"Redeemed":{"type":"boolean","nullable":true,"description":"Voucher redemption status (redeemed or not)"},"RedeemedBy":{"type":"string","description":"The user id who has redeem the vouccher (If the redemption voucher status = Redeemed)"},"RedemptionDate":{"type":"string","format":"date-time","nullable":true,"description":"Redemption date (if the redemption voucher status = redeemed)"},"SmallImage":{"type":"string","description":"The URL of the small image if exist"},"StartDate":{"type":"string","format":"date-time","nullable":true,"description":"Voucher start date"},"SubCategoryID":{"type":"integer","format":"int32","nullable":true,"description":"Voucher sub category ID"},"SubCategoryName":{"type":"string","description":"Voucher Sub category name"},"URD":{"type":"string","format":"date-time","nullable":true,"description":"Voucher create date"},"Value":{"type":"number","format":"double","nullable":true,"description":"Value of the voucher"},"VoucherCode":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"},"VoucherID":{"type":"integer","format":"int32","nullable":true,"description":"Voucher unique id"},"VoucherTypeName":{"type":"string","description":"the type of the voucher : Cash : you find the value in the field \"Value\" Product : you find the List of product codes affected by the discount in the field \"Products\" and percentage of the discount in the field \"DiscountPercentage\" Linked Products : you find the list of products should be in the basket in the field \"QualifiedBasketProducts\" and the List of product codes affected by the discount in the field \"Products\" and percentage of the discount in the field \"DiscountPercentage\" Spend : you find the amount of the basket should be in the field \"QualifiedBasketAmount\" and the List of product codes affected by the discount in the field \"Products\" and the discount is : If the field \"DiscountType\" = \"P\" then you find the percentage of the discount in the field \"DiscountPercentage\" If the field \"DiscountType\" = \"M\" then you find the amount of the discount in the field \"DiscountAmount\""}}}}},"paths":{"/api/Voucher/GetAllByCustomerIDByParams":{"get":{"operationId":"VoucherGetAllByCustomerIdByParamsGet","summary":"GetAllByCustomerIDByParams","tags":["Voucher"],"description":"Retrieves vouchers through the customer/filter lookup within the caller's authorised brands. The same source action accepts GET and POST with a complex GetAllByCustomerIDByParamsInput; the public GET entry does not describe that body. Preserve the GET catalogue entry but confirm binding/intermediary behaviour before using it; do not manufacture query expansion. The documented POST variant carries the JSON input.","responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVoucherListOutput"}}}}}}}}} ``` ## GetAllByCustomerIDByParams > Retrieves vouchers for CustomerID using the supplied offer, display, category and redemption filters. The action supplies the caller's authorised brand IDs to GetVouchersListByCustomer and returns GetVoucherListOutput. This query does not redeem or issue vouchers and does not promise that a returned voucher is currently redeemable under every checkout condition. ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"GetAllByCustomerIDByParamsInput":{"type":"object","required":["CustomerID"],"properties":{"CustomerID":{"type":"integer","format":"int32"},"CategoryIDsList":{"type":"array","nullable":true,"items":{"type":"integer","format":"int32"}},"DisplayChannelIDsList":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Get the offers that matches the provided Display Channels( optional search parameter )"},"DisplayFrom":{"type":"string","format":"date-time","nullable":true,"description":"Can be used to determine when an offer can be shown from ( optional search parameter )"},"DisplayTo":{"type":"string","format":"date-time","nullable":true,"description":"Can be used to determine when an offer can be shown to ( optional search parameter )"},"OfferID":{"type":"integer","format":"int32","nullable":true,"description":"Can be used to get only selected OfferID ( optional search parameter )"},"Redeemed":{"type":"boolean","nullable":true,"description":"Can be used to determine when an offer can be shown to ( optional search parameter )"},"RedemptionTypeIDsList":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Get the offers that matches the provided Redemption Types ( optional search parameter )"},"SubCategoryIDsList":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Get the offers that matches the provided Sub categories ( optional search parameter )"}}},"GetVoucherListOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"OfferCategories":{"type":"array","items":{"$ref":"#/components/schemas/OfferCategory"},"description":"List of Voucher categories"},"response":{"type":"boolean","description":"Status of the call"},"voucher":{"type":"array","items":{"$ref":"#/components/schemas/Voucher"},"description":"List of Voucher details"}}},"OfferCategory":{"type":"object","properties":{"CategoryImgUrl":{"type":"string","description":"Voucher category Image URL"},"CategoryOrder":{"type":"integer","format":"int32","nullable":true,"description":"Display Order"}}},"Voucher":{"type":"object","properties":{"CategoryID":{"type":"integer","format":"int32","description":"Voucher category ID"},"CategoryName":{"type":"string","description":"Voucher category name"},"Conditions":{"type":"string","description":"Terms and condition (text format)"},"CtcID":{"type":"integer","format":"int32","nullable":true,"description":"Customer id linked to this voucher"},"CtcUID":{"type":"string","description":"Customer unique id linked to this voucher"},"CustomerName":{"type":"string","description":"Customer name linked to this voucher"},"DaypartID":{"type":"integer","format":"int32","nullable":true,"description":"Used to get the predefined Schedules and Locations"},"Description":{"type":"string","description":"Voucher short description"},"Disabled":{"type":"boolean","description":"Voucher status (Disabled or not)"},"DiscountAmount":{"type":"number","format":"double","description":"Discount amount in £ (5 mean 5£)"},"DiscountPercentage":{"type":"number","format":"double","description":"Discount percentage (10 mean 10%)"},"DiscountType":{"type":"string","description":"The type of the discount \"P\" or \"M\" (if DiscountType = \"P\" so you find the percentage in the field \"DiscountPercentage\" else you find the discount amount in the field \"DiscountAmount\""},"ExpiryDate":{"type":"string","format":"date-time","nullable":true,"description":"Voucher end date"},"InfiniteVoucherRedemption":{"type":"boolean","description":"Use to determine whether the Offer Voucher's can be redeemed infinitely or not"},"IssuancePointsWorth":{"type":"number","format":"double","description":"Number of loyalty points burned from customer balance when the voucher code will be issued."},"LargeImage":{"type":"string","description":"The URL of the large image if exist"},"Location":{"type":"string","description":"The redemption location (if the redemption voucher status = reddemed)"},"MaxVoucherRedemption":{"type":"integer","format":"int32","nullable":true,"description":"Used to set the Maximum number of Vouchers that can be redeemed by Period ( PeriodDaysByVoucher ) when the InfiniteVoucherRedemption is false"},"MaxVoucherRedemptionOncePerNumberOfDays":{"type":"integer","format":"int32","nullable":true,"description":"The Voucher can be redeemed Once Per mentioned number of days if the flag InfiniteVoucherRedemption is set to true or InfiniteVoucherRedemption is false and we have a MaxVoucherRedemption value"},"MediumImage":{"type":"string","description":"The URL of the medium image if exist"},"Message":{"type":"string","description":"Voucher long description (Text format)"},"Notes":{"type":"string","description":"Voucher notes"},"OfferID":{"type":"integer","format":"int32","nullable":true,"description":"Offer unique id"},"ProductKey":{"type":"string","description":"The OfferCode"},"Products":{"type":"array","items":{"type":"string"},"description":"List of product codes affected by the discount"},"QualifiedBasketAmount":{"type":"number","format":"double","description":"List of product codes. Used if the field \"VoucherTypeName\" = \"Spend\" so the basket amount must be equal or greater this amount to validate the voucher"},"QualifiedBasketProducts":{"type":"array","items":{"type":"string"},"description":"Used if the field \"VoucherTypeName\" = \"Linked Products\" so the basket must contain all these products to validate the voucher."},"RandomID":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"},"ReactivationComment":{"type":"string","description":"Reactivation Comment"},"Redeemed":{"type":"boolean","nullable":true,"description":"Voucher redemption status (redeemed or not)"},"RedeemedBy":{"type":"string","description":"The user id who has redeem the vouccher (If the redemption voucher status = Redeemed)"},"RedemptionDate":{"type":"string","format":"date-time","nullable":true,"description":"Redemption date (if the redemption voucher status = redeemed)"},"SmallImage":{"type":"string","description":"The URL of the small image if exist"},"StartDate":{"type":"string","format":"date-time","nullable":true,"description":"Voucher start date"},"SubCategoryID":{"type":"integer","format":"int32","nullable":true,"description":"Voucher sub category ID"},"SubCategoryName":{"type":"string","description":"Voucher Sub category name"},"URD":{"type":"string","format":"date-time","nullable":true,"description":"Voucher create date"},"Value":{"type":"number","format":"double","nullable":true,"description":"Value of the voucher"},"VoucherCode":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"},"VoucherID":{"type":"integer","format":"int32","nullable":true,"description":"Voucher unique id"},"VoucherTypeName":{"type":"string","description":"the type of the voucher : Cash : you find the value in the field \"Value\" Product : you find the List of product codes affected by the discount in the field \"Products\" and percentage of the discount in the field \"DiscountPercentage\" Linked Products : you find the list of products should be in the basket in the field \"QualifiedBasketProducts\" and the List of product codes affected by the discount in the field \"Products\" and percentage of the discount in the field \"DiscountPercentage\" Spend : you find the amount of the basket should be in the field \"QualifiedBasketAmount\" and the List of product codes affected by the discount in the field \"Products\" and the discount is : If the field \"DiscountType\" = \"P\" then you find the percentage of the discount in the field \"DiscountPercentage\" If the field \"DiscountType\" = \"M\" then you find the amount of the discount in the field \"DiscountAmount\""}}}}},"paths":{"/api/Voucher/GetAllByCustomerIDByParams":{"post":{"operationId":"VoucherGetAllByCustomerIdByParamsPost","summary":"GetAllByCustomerIDByParams","tags":["Voucher"],"description":"Retrieves vouchers for CustomerID using the supplied offer, display, category and redemption filters. The action supplies the caller's authorised brand IDs to GetVouchersListByCustomer and returns GetVoucherListOutput. This query does not redeem or issue vouchers and does not promise that a returned voucher is currently redeemable under every checkout condition.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAllByCustomerIDByParamsInput"}}}},"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVoucherListOutput"}}}}}}}}} ``` ## GetByCustomerID > Get list of unredeemed vouchers related to a customer ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"GetVoucherListOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"OfferCategories":{"type":"array","items":{"$ref":"#/components/schemas/OfferCategory"},"description":"List of Voucher categories"},"response":{"type":"boolean","description":"Status of the call"},"voucher":{"type":"array","items":{"$ref":"#/components/schemas/Voucher"},"description":"List of Voucher details"}}},"OfferCategory":{"type":"object","properties":{"CategoryImgUrl":{"type":"string","description":"Voucher category Image URL"},"CategoryOrder":{"type":"integer","format":"int32","nullable":true,"description":"Display Order"}}},"Voucher":{"type":"object","properties":{"CategoryID":{"type":"integer","format":"int32","description":"Voucher category ID"},"CategoryName":{"type":"string","description":"Voucher category name"},"Conditions":{"type":"string","description":"Terms and condition (text format)"},"CtcID":{"type":"integer","format":"int32","nullable":true,"description":"Customer id linked to this voucher"},"CtcUID":{"type":"string","description":"Customer unique id linked to this voucher"},"CustomerName":{"type":"string","description":"Customer name linked to this voucher"},"DaypartID":{"type":"integer","format":"int32","nullable":true,"description":"Used to get the predefined Schedules and Locations"},"Description":{"type":"string","description":"Voucher short description"},"Disabled":{"type":"boolean","description":"Voucher status (Disabled or not)"},"DiscountAmount":{"type":"number","format":"double","description":"Discount amount in £ (5 mean 5£)"},"DiscountPercentage":{"type":"number","format":"double","description":"Discount percentage (10 mean 10%)"},"DiscountType":{"type":"string","description":"The type of the discount \"P\" or \"M\" (if DiscountType = \"P\" so you find the percentage in the field \"DiscountPercentage\" else you find the discount amount in the field \"DiscountAmount\""},"ExpiryDate":{"type":"string","format":"date-time","nullable":true,"description":"Voucher end date"},"InfiniteVoucherRedemption":{"type":"boolean","description":"Use to determine whether the Offer Voucher's can be redeemed infinitely or not"},"IssuancePointsWorth":{"type":"number","format":"double","description":"Number of loyalty points burned from customer balance when the voucher code will be issued."},"LargeImage":{"type":"string","description":"The URL of the large image if exist"},"Location":{"type":"string","description":"The redemption location (if the redemption voucher status = reddemed)"},"MaxVoucherRedemption":{"type":"integer","format":"int32","nullable":true,"description":"Used to set the Maximum number of Vouchers that can be redeemed by Period ( PeriodDaysByVoucher ) when the InfiniteVoucherRedemption is false"},"MaxVoucherRedemptionOncePerNumberOfDays":{"type":"integer","format":"int32","nullable":true,"description":"The Voucher can be redeemed Once Per mentioned number of days if the flag InfiniteVoucherRedemption is set to true or InfiniteVoucherRedemption is false and we have a MaxVoucherRedemption value"},"MediumImage":{"type":"string","description":"The URL of the medium image if exist"},"Message":{"type":"string","description":"Voucher long description (Text format)"},"Notes":{"type":"string","description":"Voucher notes"},"OfferID":{"type":"integer","format":"int32","nullable":true,"description":"Offer unique id"},"ProductKey":{"type":"string","description":"The OfferCode"},"Products":{"type":"array","items":{"type":"string"},"description":"List of product codes affected by the discount"},"QualifiedBasketAmount":{"type":"number","format":"double","description":"List of product codes. Used if the field \"VoucherTypeName\" = \"Spend\" so the basket amount must be equal or greater this amount to validate the voucher"},"QualifiedBasketProducts":{"type":"array","items":{"type":"string"},"description":"Used if the field \"VoucherTypeName\" = \"Linked Products\" so the basket must contain all these products to validate the voucher."},"RandomID":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"},"ReactivationComment":{"type":"string","description":"Reactivation Comment"},"Redeemed":{"type":"boolean","nullable":true,"description":"Voucher redemption status (redeemed or not)"},"RedeemedBy":{"type":"string","description":"The user id who has redeem the vouccher (If the redemption voucher status = Redeemed)"},"RedemptionDate":{"type":"string","format":"date-time","nullable":true,"description":"Redemption date (if the redemption voucher status = redeemed)"},"SmallImage":{"type":"string","description":"The URL of the small image if exist"},"StartDate":{"type":"string","format":"date-time","nullable":true,"description":"Voucher start date"},"SubCategoryID":{"type":"integer","format":"int32","nullable":true,"description":"Voucher sub category ID"},"SubCategoryName":{"type":"string","description":"Voucher Sub category name"},"URD":{"type":"string","format":"date-time","nullable":true,"description":"Voucher create date"},"Value":{"type":"number","format":"double","nullable":true,"description":"Value of the voucher"},"VoucherCode":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"},"VoucherID":{"type":"integer","format":"int32","nullable":true,"description":"Voucher unique id"},"VoucherTypeName":{"type":"string","description":"the type of the voucher : Cash : you find the value in the field \"Value\" Product : you find the List of product codes affected by the discount in the field \"Products\" and percentage of the discount in the field \"DiscountPercentage\" Linked Products : you find the list of products should be in the basket in the field \"QualifiedBasketProducts\" and the List of product codes affected by the discount in the field \"Products\" and percentage of the discount in the field \"DiscountPercentage\" Spend : you find the amount of the basket should be in the field \"QualifiedBasketAmount\" and the List of product codes affected by the discount in the field \"Products\" and the discount is : If the field \"DiscountType\" = \"P\" then you find the percentage of the discount in the field \"DiscountPercentage\" If the field \"DiscountType\" = \"M\" then you find the amount of the discount in the field \"DiscountAmount\""}}}}},"paths":{"/api/Voucher/GetByCustomerID":{"get":{"operationId":"VoucherGetByCustomerId","summary":"GetByCustomerID","tags":["Voucher"],"description":"Get list of unredeemed vouchers related to a customer","parameters":[{"name":"customerid","in":"query","schema":{"type":"integer","format":"int32"},"description":"Native query parameter. CLR int customerid in the pinned controller signature.","required":true}],"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVoucherListOutput"}}}}}}}}} ``` ## GetCategoriesAndSubCategories > Get Categories ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"OfferCategory":{"type":"object","properties":{"CategoryImgUrl":{"type":"string","description":"Voucher category Image URL"},"CategoryOrder":{"type":"integer","format":"int32","nullable":true,"description":"Display Order"}}}}},"paths":{"/api/Voucher/GetCategoriesAndSubCategories":{"get":{"operationId":"VoucherGetCategoriesAndSubCategories","summary":"GetCategoriesAndSubCategories","tags":["Voucher"],"description":"Get Categories","responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OfferCategory"}}}}}}}}}} ``` ## GetCustomersPerOfferByParams > Retrieves customer information through the supplied offer/filter lookup and returns CustomersPerOfferByParamsOutput. The shared source action accepts a complex input for GET and POST, while this catalogue GET has no body contract. Confirm binding before use; neither query expansion nor gateway forwarding is established by the method name. No voucher issuance or redemption is implied. ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"CustomersPerOfferByParamsOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"response":{"type":"boolean","description":"Status of the call"}}}}},"paths":{"/api/Voucher/GetCustomersPerOfferByParams":{"get":{"operationId":"VoucherGetCustomersPerOfferByParamsGet","summary":"GetCustomersPerOfferByParams","tags":["Voucher"],"description":"Retrieves customer information through the supplied offer/filter lookup and returns CustomersPerOfferByParamsOutput. The shared source action accepts a complex input for GET and POST, while this catalogue GET has no body contract. Confirm binding before use; neither query expansion nor gateway forwarding is established by the method name. No voucher issuance or redemption is implied.","responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomersPerOfferByParamsOutput"}}}}}}}}} ``` ## GetCustomersPerOfferByParams > Queries customer details using CustomersPerOfferByParamsInput and returns CustomersPerOfferByParamsOutput. This POST is a lookup with a JSON filter body, not a voucher-redemption operation. Treat returned customer information as personal data and retain only fields authorised for the integration. ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"CustomersPerOfferByParamsInput":{"type":"object","properties":{"SourceID":{"type":"string","description":"OriginID will be returned only if SourceID is provided"}}},"CustomersPerOfferByParamsOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"response":{"type":"boolean","description":"Status of the call"}}}}},"paths":{"/api/Voucher/GetCustomersPerOfferByParams":{"post":{"operationId":"VoucherGetCustomersPerOfferByParamsPost","summary":"GetCustomersPerOfferByParams","tags":["Voucher"],"description":"Queries customer details using CustomersPerOfferByParamsInput and returns CustomersPerOfferByParamsOutput. This POST is a lookup with a JSON filter body, not a voucher-redemption operation. Treat returned customer information as personal data and retain only fields authorised for the integration.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomersPerOfferByParamsInput"}}}},"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomersPerOfferByParamsOutput"}}}}}}}}} ``` ## GetOfferRemainingRedemptions > Looks up the remaining-redemption value for OfferID and returns RemainingRedemptionsOutput with lowercase response and errors. RemainingRedemptions is nullable. This lookup neither reserves availability nor guarantees a later redemption will succeed; inspect the result flags and current offer conditions. ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"RemainingRedemptionsOutput":{"type":"object","nullable":true,"properties":{"response":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string","nullable":true},"nullable":true},"RemainingRedemptions":{"type":"integer","format":"int32","nullable":true}},"description":"Source-backed JSON members, including inheritance and JSON naming/ignore attributes. No property is required solely because its CLR value type is non-nullable. Runtime and deployment alignment are unverified."}}},"paths":{"/api/Voucher/GetOfferRemainingRedemptions":{"get":{"operationId":"VoucherGetOfferRemainingRedemptionsGet","summary":"GetOfferRemainingRedemptions","tags":["Voucher"],"description":"Looks up the remaining-redemption value for OfferID and returns RemainingRedemptionsOutput with lowercase response and errors. RemainingRedemptions is nullable. This lookup neither reserves availability nor guarantees a later redemption will succeed; inspect the result flags and current offer conditions.","parameters":[{"name":"OfferID","in":"query","schema":{"type":"integer","format":"int32"},"description":"Native query parameter. CLR int OfferID in the pinned controller signature.","required":true}],"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemainingRedemptionsOutput"}}}}}}}}} ``` ## GetOfferRemainingRedemptions > POST variant of the remaining-redemption lookup. OfferID remains a URI/query parameter in the shared source action, not an invented JSON body. Returns the nullable RemainingRedemptions value beside lowercase response and errors; it does not reserve or redeem a voucher. ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"RemainingRedemptionsOutput":{"type":"object","nullable":true,"properties":{"response":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string","nullable":true},"nullable":true},"RemainingRedemptions":{"type":"integer","format":"int32","nullable":true}},"description":"Source-backed JSON members, including inheritance and JSON naming/ignore attributes. No property is required solely because its CLR value type is non-nullable. Runtime and deployment alignment are unverified."}}},"paths":{"/api/Voucher/GetOfferRemainingRedemptions":{"post":{"operationId":"VoucherGetOfferRemainingRedemptionsPost","summary":"GetOfferRemainingRedemptions","tags":["Voucher"],"description":"POST variant of the remaining-redemption lookup. OfferID remains a URI/query parameter in the shared source action, not an invented JSON body. Returns the nullable RemainingRedemptions value beside lowercase response and errors; it does not reserve or redeem a voucher.","parameters":[{"name":"OfferID","in":"query","schema":{"type":"integer","format":"int32"},"description":"Native query parameter. CLR int OfferID in the pinned controller signature.","required":true}],"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemainingRedemptionsOutput"}}}}}}}}} ``` ## GetOffersByParams > Retrieves filtered offer details, including the action's authorised-brand and location/schedule processing. The source shares a complex OfferByParamsInput across GET and POST, but this catalogue GET does not define that body. Keep the catalogue route unchanged and verify binding/intermediary behaviour rather than invent query parameters. Returned offer data is not a redemption or reservation guarantee. ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"Offers":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"response":{"type":"boolean","description":"Status of the call"}}}}},"paths":{"/api/Voucher/GetOffersByParams":{"get":{"operationId":"VoucherGetOffersByParamsGet","summary":"GetOffersByParams","tags":["Voucher"],"description":"Retrieves filtered offer details, including the action's authorised-brand and location/schedule processing. The source shares a complex OfferByParamsInput across GET and POST, but this catalogue GET does not define that body. Keep the catalogue route unchanged and verify binding/intermediary behaviour rather than invent query parameters. Returned offer data is not a redemption or reservation guarantee.","responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Offers"}}}}}}}}} ``` ## GetOffersByParams > Retrieves offer details using the supplied OfferByParamsInput, with authorised-brand and location/schedule processing in the action. Returns Offers. Filtering and eligibility depend on the instance's offer data; this query does not issue, reserve or redeem a voucher. ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"OfferByParamsInput":{"type":"object","properties":{"CategoryIDsList":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Get the offers that matches the provided categories ( optional search parameter )"},"DisplayChannelIDsList":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Get the offers that matches the provided Display Channels( optional search parameter )"},"DisplayFrom":{"type":"string","format":"date-time","nullable":true,"description":"Get the offers the their display Date is greated than the provided date ( optional search parameter )"},"OfferCode":{"type":"string","description":"Get the offers that matches the provided Offer Code ( optional search parameter )"},"OnlyActiveOffers":{"type":"boolean","description":"Expired and paused offers will be excluded where the value is true ( optional search parameter )"},"RedemptionLocationID":{"type":"integer","format":"int32","nullable":true,"description":"Get the offers that can be redeemed in the provided Location ID ( optional search parameter )"},"RedemptionTypeIDsList":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Get the offers that matches the provided Redemption Types ( optional search parameter )"},"StartDate":{"type":"string","format":"date-time","nullable":true,"description":"Get the offers the their Start Date is greated than the provided date ( optional search parameter )"},"SubCategoryIDsList":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Get the offers that matches the provided Sub categories ( optional search parameter )"},"VoucherTypeIDsList":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Get the offers that matches the provided Voucher Types ( optional search parameter )"}}},"Offers":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"response":{"type":"boolean","description":"Status of the call"}}}}},"paths":{"/api/Voucher/GetOffersByParams":{"post":{"operationId":"VoucherGetOffersByParamsPost","summary":"GetOffersByParams","tags":["Voucher"],"description":"Retrieves offer details using the supplied OfferByParamsInput, with authorised-brand and location/schedule processing in the action. Returns Offers. Filtering and eligibility depend on the instance's offer data; this query does not issue, reserve or redeem a voucher.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferByParamsInput"}}}},"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Offers"}}}}}}}}} ``` ## GetOrderTypes > Get Order Types ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"SubCategory":{"type":"object","nullable":true,"properties":{"SubCategoryID":{"type":"integer","format":"int32"},"SubCategoryName":{"type":"string","nullable":true},"CategoryID":{"type":"integer","format":"int32"}},"description":"Source-backed JSON members, including inheritance and JSON naming/ignore attributes. No property is required solely because its CLR value type is non-nullable. Runtime and deployment alignment are unverified."}}},"paths":{"/api/Voucher/GetOrderTypes":{"get":{"operationId":"VoucherGetOrderTypes","summary":"GetOrderTypes","tags":["Voucher"],"description":"Get Order Types","responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SubCategory"}}}}}}}}}} ``` ## GetVouchersIssuedByOffer > Retrieves vouchers already issued for the requested offer/filter context; it does not issue new vouchers. The shared source action takes GetVouchersIssuedByOfferInput for GET and POST, whereas this catalogue GET has no request-body contract. Confirm binding before use and preserve the documented POST body variant. ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"GetVouchersIssuedByOfferOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"response":{"type":"boolean","description":"Status of the call"}}}}},"paths":{"/api/Voucher/GetVouchersIssuedByOffer":{"get":{"operationId":"VoucherGetVouchersIssuedByOfferGet","summary":"GetVouchersIssuedByOffer","tags":["Voucher"],"description":"Retrieves vouchers already issued for the requested offer/filter context; it does not issue new vouchers. The shared source action takes GetVouchersIssuedByOfferInput for GET and POST, whereas this catalogue GET has no request-body contract. Confirm binding before use and preserve the documented POST body variant.","responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVouchersIssuedByOfferOutput"}}}}}}}}} ``` ## GetVouchersIssuedByOffer > Queries vouchers already issued for the supplied offer, date, disabled/redeemed and source filters. Returns GetVouchersIssuedByOfferOutput with native lowercase status/error fields. It is a lookup, not a command to issue or redeem vouchers; valid identifiers and result contents depend on instance data. ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"GetVouchersIssuedByOfferInput":{"type":"object","nullable":true,"properties":{"OfferID":{"type":"integer","format":"int32"},"StartDate":{"type":"string","format":"date-time","nullable":true},"EndDate":{"type":"string","format":"date-time","nullable":true},"Disabled":{"type":"boolean","nullable":true},"Redeemed":{"type":"boolean","nullable":true},"SourceID":{"type":"string","nullable":true}},"description":"Source-backed JSON members, including inheritance and JSON naming/ignore attributes. No property is required solely because its CLR value type is non-nullable. Runtime and deployment alignment are unverified."},"GetVouchersIssuedByOfferOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"response":{"type":"boolean","description":"Status of the call"}}}}},"paths":{"/api/Voucher/GetVouchersIssuedByOffer":{"post":{"operationId":"VoucherGetVouchersIssuedByOfferPost","summary":"GetVouchersIssuedByOffer","tags":["Voucher"],"description":"Queries vouchers already issued for the supplied offer, date, disabled/redeemed and source filters. Returns GetVouchersIssuedByOfferOutput with native lowercase status/error fields. It is a lookup, not a command to issue or redeem vouchers; valid identifiers and result contents depend on instance data.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVouchersIssuedByOfferInput"}}}},"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVouchersIssuedByOfferOutput"}}}}}}}}} ``` ## GetVoucherTypes > Get Voucher Types ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"VoucherType":{"type":"object","nullable":true,"properties":{"VoucherTypeID":{"type":"integer","format":"int32"},"VoucherTypeName":{"type":"string","nullable":true}},"description":"Source-backed JSON members, including inheritance and JSON naming/ignore attributes. No property is required solely because its CLR value type is non-nullable. Runtime and deployment alignment are unverified."}}},"paths":{"/api/Voucher/GetVoucherTypes":{"get":{"operationId":"VoucherGetVoucherTypes","summary":"GetVoucherTypes","tags":["Voucher"],"description":"Get Voucher Types","responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VoucherType"}}}}}}}}}} ``` ## Reactivate > Reactivate a voucher ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"ReactivateVoucherInput":{"type":"object","properties":{"Comments":{"type":"string","description":"Comments"}}},"ReactivateVoucherOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"response":{"type":"boolean","description":"Status of the call"}}}}},"paths":{"/api/Voucher/Reactivate":{"post":{"operationId":"VoucherReactivate","summary":"Reactivate","tags":["Voucher"],"description":"Reactivate a voucher","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReactivateVoucherInput"}}}},"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReactivateVoucherOutput"}}}}}}}}} ``` ## Redeem > Redeem voucher ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"RedeemVoucherInput":{"type":"object","properties":{"birthdate":{"type":"string","format":"date-time","nullable":true,"description":"Birthdate of the customer if it's anonymous voucher"},"CustomerID":{"type":"integer","format":"int32","description":"the ctcid of the contact (if the voucher is anonymous, it will be linked to this CustomerID)"},"email":{"type":"string","description":"Email of the customer if it's anonymous voucher"},"firstname":{"type":"string","description":"First name of the customer if it's anonymous voucher"},"lastname":{"type":"string","description":"Last name of the customer if it's anonymous voucher"},"mobile":{"type":"string","description":"Mobile phone of the customer if it's anonymous voucher"},"OrderAmount":{"type":"number","format":"double","nullable":true,"description":"The amount of the order"},"OrderID":{"type":"string","description":"This will be used to validate voucher if it's reseved"},"RedemptionDate":{"type":"string","format":"date-time","nullable":true,"description":"Date when the voucher has been redeemed"},"RedemptionLocationID":{"type":"integer","format":"int32","nullable":true,"description":"Location ID where the voucher will be redeemed"},"RedemptionLocationName":{"type":"string","description":"Location Name where the voucher will be redeemed"},"redemptionType":{"description":"The redemption type of the voucher (Documented as type `RedemptionType`. No values are listed on this property; the published description of `ValidateVoucherInput.redemptionType` lists values for the same type name, which is not evidence that the same list applies here.)","type":"integer","format":"int32"},"VoucherAmount":{"type":"number","format":"double","nullable":true,"description":"The amount of the voucher"},"vouchercode":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"}},"required":["vouchercode"]},"RedeemVoucherOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"ProductKey":{"type":"string","description":"Product Key"},"RedemptionKey":{"type":"integer","format":"int32","description":"integer key starting from 1000 to 9999 (the key is generated per day)"},"response":{"type":"boolean","description":"List of errors if exists"}}}}},"paths":{"/api/Voucher/Redeem":{"post":{"operationId":"VoucherRedeem","summary":"Redeem","tags":["Voucher"],"description":"Redeem voucher","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemVoucherInput"}}}},"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemVoucherOutput"}}}}}}}}} ``` ## ValidateVoucher > Validate voucher ```json {"openapi":"3.0.3","info":{"title":"Atreemo API","version":"0.1.0"},"tags":[{"name":"Voucher","description":"Api Methods for Voucher"}],"servers":[{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/atreemo-api","description":"Local DEV APIM import draft only; not a deployed endpoint announcement."}],"security":[{"AtreemoBearer":[]}],"components":{"securitySchemes":{"AtreemoBearer":{"type":"http","scheme":"bearer","description":"Atreemo access token obtained by the caller from the Atreemo instance `POST /token` endpoint (OAuth2 password grant) and sent as `Authorization: Bearer `. See the Authorisation guide."}},"schemas":{"ValidateVoucherInput":{"type":"object","properties":{"CustomerID":{"type":"integer","format":"int32","description":"the ctcid of the contact (if the voucher is anonymous, it will be linked to this CustomerID)"},"redemptionType":{"description":"redemptionType type InStore = 1, Collection = 2, Delivery = 3, Shop = 7, PayAtTable = 8, PreOrder = 9 (Documented as type `RedemptionType`. The published description lists the values captured in `x-atreemo-documented-values`; their wire representation (number or name) and whether the list is exhaustive are not documented.)","type":"integer","format":"int32"},"ReservedFor":{"type":"string","description":"this ID will be used in the redemption (if empty we will use the user ID connected)"},"ReserveIt":{"type":"boolean","description":"Reserve it for 30 mn if needed"},"VoucherAmount":{"type":"number","format":"double","nullable":true,"description":"The amount of the voucher"},"vouchercode":{"type":"string","description":"Voucher code \"OfferCode-9999999\" (like Coke-9999999)"}},"required":["vouchercode"]},"ValidateVoucherOutput":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of errors if exists"},"ProductKey":{"type":"string","description":"Product Key"},"RedemptionID":{"type":"integer","format":"int32","description":"RedemptionID"},"response":{"type":"boolean","description":"List of errors if exists"}}}}},"paths":{"/api/Voucher/ValidateVoucher":{"post":{"operationId":"VoucherValidateVoucher","summary":"ValidateVoucher","tags":["Voucher"],"description":"Validate voucher","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateVoucherInput"}}}},"responses":{"200":{"description":"OK (sample status in the public collection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateVoucherOutput"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.hos.accessacloud.com/atreemo-api/api-reference/atreemo-api-reference/voucher.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.