{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer-portal/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Voyado Loyalty Adapter","description":"Home of the Norce Commerce documentation"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"voyado-loyalty-adapter"},"children":["Voyado Loyalty Adapter"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Overview Document:"]}," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-portal/app-development/nco/loyalty-adapters"},"children":["Loyalty Adapters Overview"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview-and-unique-capabilities"},"children":["Overview and Unique Capabilities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Voyado Loyalty Adapter integrates Voyado Engage with Norce Checkout. It"," ","links a Voyado contact to a Norce Checkout order and exposes the Voyado"," ","promotions and reward vouchers available to that contact. When a promotion"," ","or reward voucher is applied, the adapter writes it to"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty"]}," so that the Norce Adapter can translate it into a"," ","discount line item in Norce Commerce."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The adapter id used in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.provider"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Voyado"]},". The"," ","adapter itself is identified in Norce Checkout Admin as"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voyado_checkout_adapter"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"supported-operations"},"children":["Supported operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Voyado Loyalty Adapter exposes three sets of endpoints under"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1"]},":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Area"},"children":["Area"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Endpoints"},"children":["Endpoints"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Loyalty"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /loyalty/{orderId}/set"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Promotions"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /promotions/{orderId}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /promotions/{orderId}/{promotionId}/apply"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /promotions/{orderId}/{promotionId}/remove"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Reward vouchers"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /rewardvouchers/{orderId}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /rewardvouchers/{orderId}/{voucherId}/apply"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /rewardvouchers/{orderId}/{voucherId}/remove"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"limitations"},"children":["Limitations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Voyado Loyalty Adapter does not register receipts or transactions in"," ","Voyado. No purchase data is pushed to Voyado by this adapter. If you need"," ","receipt/transaction synchronization with Voyado, it is currently handled by"," ","third-party integration partners such as ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://nexergroup.com/services/unified-commerce/commerce-integration-platform/"},"children":["Nexer Group's Commerce"," ","Integration Platform"]},","," ","not by this adapter."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All promotion and reward-voucher endpoints require"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.id"]}," to be set by"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/loyalty/{orderId}/set"]}," first. Otherwise the adapter returns"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loyalty-id-missing"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reward vouchers require ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardVoucherLevels"]}," to be configured. An"," ","applied voucher whose amount does not match any configured level is"," ","rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configuration-error"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Promotions without an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}," and without a usable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ECOM"]}," redemption"," ","channel value are rejected on apply with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["promotion-external-id-missing"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration-in-norce-admin"},"children":["Configuration in Norce Admin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Voyado Loyalty Adapter is configured per merchant/channel in Norce"," ","Checkout Admin. The configuration is validated against the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voyado_adapter"]}," JSON schema published by the adapter."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"required-configuration"},"children":["Required configuration"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Example Value"},"children":["Example Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adapter.internalUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Internal URL of the Voyado Loyalty Adapter, used by other Norce services."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://voyado-adapter.checkout.playground.internal.norce.tech"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adapter.publicUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Public URL of the Voyado Loyalty Adapter, used by the storefront. Must contain your slug."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://{slug}.api-se.playground.norce.tech/checkout/voyado-adapter"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiSettings.apiUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Base URL of the Voyado Engage API. Use the staging URL in test and the production URL in live."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://yourclient.voyado.com"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiSettings.apiKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Voyado Engage API key. Sent as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey"]}," header on every outgoing call to Voyado."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["***"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reward-voucher-levels"},"children":["Reward voucher levels"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardVoucherLevels"]}," maps Voyado reward vouchers to Norce discount"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}," values based on the voucher amount."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardVoucherLevels[].maxAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Upper bound (inclusive) of the voucher amount for this level."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardVoucherLevels[].externalId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Norce discount ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}," written to the order when a voucher of this level is applied."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Levels are evaluated in ascending ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maxAmount"]}," order. The first level whose"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maxAmount"]}," is greater than or equal to the voucher amount wins. If no level"," ","matches, applying the voucher fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configuration-error"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"$schema\": \"https://{slug}.api-se.playground.norce.tech/checkout/voyado-adapter/openapi/v1/schemas/voyado_adapter.json\",\n  \"id\": \"voyado_adapter\",\n  \"active\": true,\n  \"adapter\": {\n    \"internalUrl\": \"https://voyado-adapter.checkout.playground.internal.norce.tech\",\n    \"publicUrl\": \"https://{slug}.api-se.playground.norce.tech/checkout/voyado-adapter\"\n  },\n  \"apiSettings\": {\n    \"apiUrl\": \"https://yourclient.voyado.com\",\n    \"apiKey\": \"***\"\n  },\n  \"rewardVoucherLevels\": [\n    { \"maxAmount\": 100, \"externalId\": \"VOYADO_VOUCHER_100\" },\n    { \"maxAmount\": 250, \"externalId\": \"VOYADO_VOUCHER_250\" },\n    { \"maxAmount\": 500, \"externalId\": \"VOYADO_VOUCHER_500\" }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"matching-voyado-promotions-and-reward-vouchers-to-norce-commerce-promotions"},"children":["Matching Voyado promotions and reward vouchers to Norce Commerce promotions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCode"]}," that the Voyado Loyalty Adapter writes to the order"," ","(from a Voyado promotion or from a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardVoucherLevels[].externalId"]},") must"," ","exist as a Promotion in Norce Commerce Admin. Without a matching Promotion,"," ","the order will contain the loyalty entry but no corresponding discount line"," ","in Norce Commerce."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For each expected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCode"]},", create a Promotion in Norce Commerce"," ","Admin with:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Code"]}," — a unique code for the promotion (free-form)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Status"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Active"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Requirement"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["If the external discount code is <externalCode>"]},","," ","where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<externalCode>"]}," is exactly one of:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A Voyado promotion ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," of the Voyado promotion's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ECOM"]}," redemption channel (when"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}," is empty)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardVoucherLevels[].externalId"]}," value from the adapter"," ","configuration (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VOYADO_VOUCHER_100"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RewardVoucher-600"]},")."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Effect"]}," — the discount that should be applied (for example"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["THEN Discount all in basket with 600,00 SEK incl. VAT"]}," for a 600 SEK"," ","reward voucher, or a percentage discount for a promotion)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a Voyado promotion or reward voucher is applied through the adapter,"," ","the Norce Adapter looks for a Norce Commerce Promotion whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external discount code"]}," requirement matches the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCode"]}," on the order and"," ","adds the corresponding discount line item to the cart. If no matching"," ","Promotion exists, no discount is applied."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-norce-commerce-promotion-for-a-voyado-reward-voucher"},"children":["Example: Norce Commerce Promotion for a Voyado reward voucher"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A Voyado reward voucher of 600 SEK, mapped by"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardVoucherLevels"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId = \"RewardVoucher-600\""]},", requires a"," ","Norce Commerce Promotion whose Requirement is"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IF External discount code is RewardVoucher-600"]}," and whose Effect is"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["THEN Discount all in basket with 600,00 SEK incl. VAT"]},":"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/voyado-norce-admin-reward-voucher-promotion.be67c35f8f37743accb2844f0669d4573f09bf50bd4cc2d5598877acbfc9657e.1912a556.png","alt":"Norce Commerce Admin Promotion with Requirement 'IF External discount code is RewardVoucher-600' and Effect 'THEN Discount all in basket with 600,00 SEK incl. VAT'"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-norce-commerce-promotion-for-a-voyado-promotion"},"children":["Example: Norce Commerce Promotion for a Voyado promotion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A Voyado promotion whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCode"]}," resolves to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NEWCUSTOMER"]}," ","(either directly from the Voyado ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}," or from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ECOM"]}," ","redemption channel value) requires a Norce Commerce Promotion whose"," ","Requirement is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IF External discount code is NEWCUSTOMER"]}," and whose"," ","Effect is, for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["THEN Discount all in basket with 10,00 %"]},":"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/voyado-norce-admin-voyado-promotion.97497cf425b3a2fca1500eb7c573f2f6747bf51f13ae2617f1b095ff93228a19.1912a556.png","alt":"Norce Commerce Admin Promotion with Requirement 'IF External discount code is NEWCUSTOMER' and Effect 'THEN Discount all in basket with 10,00 %'"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"setting-the-voyado-contact-on-the-order"},"children":["Setting the Voyado Contact on the Order"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/loyalty/{orderId}/set"]}," to link a Voyado contact to a"," ","Norce Checkout order. The adapter validates the contact against Voyado,"," ","stores it on the order, and returns the contact together with the"," ","promotions and reward vouchers the contact is entitled to."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/loyalty/{order_id}/set\nHost: {slug}.api-se.stage.norce.tech\nx-merchant: {merchant}\nx-channel: {channel}\nAuthorization: Bearer {token}\nContent-Type: application/json\n\n{\n  \"voyadoId\": \"a7f3c1b2-.....\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On success the adapter:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.id"]}," to the provided ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voyadoId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.provider"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Voyado\""]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ContactDetailsResponse"]}," with the Voyado contact, the contact's"," ","active promotions, and their available reward vouchers."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Required after set loyalty"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All other Voyado Loyalty Adapter endpoints read"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.id"]},". Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/loyalty/{orderId}/set"]}," ","before calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apply"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remove"]}," for promotions or reward"," ","vouchers. If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.id"]}," is missing, the adapter returns"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loyalty-id-missing"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"working-with-voyado-promotions"},"children":["Working with Voyado Promotions"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"listing-promotions"},"children":["Listing promotions"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /api/v1/promotions/{order_id}\nHost: {slug}.api-se.stage.norce.tech\nx-merchant: {merchant}\nx-channel: {channel}\nAuthorization: Bearer {token}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The adapter calls Voyado's"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET api/v3/promotion-assignments?contactId={loyaltyId}"]}," and returns the"," ","promotions for the contact stored on the order."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"applying-a-promotion"},"children":["Applying a promotion"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/promotions/{order_id}/{promotion_id}/apply\nHost: {slug}.api-se.stage.norce.tech\nx-merchant: {merchant}\nx-channel: {channel}\nAuthorization: Bearer {token}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On apply, the adapter resolves an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCode"]}," for the promotion and"," ","writes it to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.promotions[]"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCode"]}," is resolved in this order:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the Voyado promotion's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}," is non-empty, it is used."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Otherwise, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," of the redemption channel whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," is"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ECOM"]}," (case-insensitive) is used. Both string and numeric ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," ","types are supported."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If neither is available, the call fails with"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["promotion-external-id-missing"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Applying a promotion that has already been redeemed in Voyado, or that is"," ","already on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.promotions[]"]},", fails with"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voyado-bad-request"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"removing-a-promotion"},"children":["Removing a promotion"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/promotions/{order_id}/{promotion_id}/remove\nHost: {slug}.api-se.stage.norce.tech\nx-merchant: {merchant}\nx-channel: {channel}\nAuthorization: Bearer {token}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The adapter removes the promotion from"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.promotions[]"]}," by matching either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," or"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCode"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"working-with-voyado-reward-vouchers"},"children":["Working with Voyado Reward Vouchers"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"listing-reward-vouchers"},"children":["Listing reward vouchers"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /api/v1/rewardvouchers/{order_id}\nHost: {slug}.api-se.stage.norce.tech\nx-merchant: {merchant}\nx-channel: {channel}\nAuthorization: Bearer {token}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The adapter calls Voyado's"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET api/v3/reward-vouchers/available?contactId={loyaltyId}"]}," and returns the"," ","available reward vouchers for the contact stored on the order."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"applying-a-reward-voucher"},"children":["Applying a reward voucher"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/rewardvouchers/{order_id}/{voucher_id}/apply\nHost: {slug}.api-se.stage.norce.tech\nx-merchant: {merchant}\nx-channel: {channel}\nAuthorization: Bearer {token}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On apply, the adapter:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rejects the call with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voucher-invalid"]}," if the voucher is already"," ","redeemed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resolves an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCode"]}," from the configured ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardVoucherLevels"]}," ","(the first level where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voucher.value.amount <= maxAmount"]}," wins)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Writes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LoyaltyRewardVoucher"]}," entry to"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.rewardVouchers[]"]}," containing the Voyado ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voucherNumber"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},", and resolved ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCode"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Applying a voucher that is already on"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.rewardVouchers[]"]}," fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voyado-bad-request"]},"."," ","Applying a voucher whose amount does not match any configured level fails"," ","with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configuration-error"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"removing-a-reward-voucher"},"children":["Removing a reward voucher"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/rewardvouchers/{order_id}/{voucher_id}/remove\nHost: {slug}.api-se.stage.norce.tech\nx-merchant: {merchant}\nx-channel: {channel}\nAuthorization: Bearer {token}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The adapter removes the voucher from"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.rewardVouchers[]"]}," by matching either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," or"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voucherNumber"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting-voyado-specific"},"children":["Troubleshooting (Voyado Specific)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition to the generic troubleshooting steps:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiSettings.apiUrl"]}," points to the correct Voyado environment"," ","(",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://{client}.staging.voyado.com"]}," for test,"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://{client}.voyado.com"]}," for production)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiSettings.apiKey"]}," is valid and has access to"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api/v3/contacts/{id}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api/v3/promotion-assignments"]},", and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api/v3/reward-vouchers/available"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.customer.loyalty.id"]}," is set before calling promotion"," ","or reward-voucher endpoints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that each Voyado promotion intended for ECOM has either an"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}," or a non-empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ECOM"]}," redemption channel ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that every voucher amount your Voyado tenant issues is covered by"," ","a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardVoucherLevel"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCode"]}," the adapter writes has a matching"," ","Promotion in Norce Commerce Admin whose requirement is"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["If the external discount code is <externalCode>"]},". Without it, no"," ","discount line item is added to the cart even though the loyalty entry"," ","is on the order."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-codes"},"children":["Error Codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Error Code"},"children":["Error Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voyado-contact-not-found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The Voyado contact id used on the request does not exist in the configured Voyado tenant."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voyado-promotion-not-found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The promotion id on an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apply"]}," call is not in the list returned by Voyado for this contact."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voyado-voucher-not-found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The voucher id on an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apply"]}," call is not in the list returned by Voyado for this contact."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loyalty-id-missing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The order does not have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer.loyalty.id"]}," set. Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/loyalty/{orderId}/set"]}," first."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["promotion-external-id-missing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The promotion has no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}," and no usable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ECOM"]}," redemption channel value, so no Norce discount code can be resolved."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["promotion-not-applied"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Writing the promotion to the order failed validation on the order service."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voucher-invalid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The reward voucher is already redeemed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voucher-not-applied"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Writing the reward voucher to the order failed validation on the order service."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configuration-error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The adapter configuration is missing or the voucher amount does not match any configured ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardVoucherLevel"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voyado-bad-request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The promotion or reward voucher is already applied to the order, or is already redeemed in Voyado."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"links-and-references"},"children":["Links and References"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://voyado.com/"},"children":["Voyado Engage"]}," (contact Voyado for API documentation)"]}]}]},"headings":[{"value":"Voyado Loyalty Adapter","id":"voyado-loyalty-adapter","depth":1},{"value":"Overview and Unique Capabilities","id":"overview-and-unique-capabilities","depth":2},{"value":"Supported operations","id":"supported-operations","depth":3},{"value":"Limitations","id":"limitations","depth":3},{"value":"Configuration in Norce Admin","id":"configuration-in-norce-admin","depth":2},{"value":"Required configuration","id":"required-configuration","depth":3},{"value":"Reward voucher levels","id":"reward-voucher-levels","depth":3},{"value":"Matching Voyado promotions and reward vouchers to Norce Commerce promotions","id":"matching-voyado-promotions-and-reward-vouchers-to-norce-commerce-promotions","depth":2},{"value":"Example: Norce Commerce Promotion for a Voyado reward voucher","id":"example-norce-commerce-promotion-for-a-voyado-reward-voucher","depth":3},{"value":"Example: Norce Commerce Promotion for a Voyado promotion","id":"example-norce-commerce-promotion-for-a-voyado-promotion","depth":3},{"value":"Setting the Voyado Contact on the Order","id":"setting-the-voyado-contact-on-the-order","depth":2},{"value":"Working with Voyado Promotions","id":"working-with-voyado-promotions","depth":2},{"value":"Listing promotions","id":"listing-promotions","depth":3},{"value":"Applying a promotion","id":"applying-a-promotion","depth":3},{"value":"Removing a promotion","id":"removing-a-promotion","depth":3},{"value":"Working with Voyado Reward Vouchers","id":"working-with-voyado-reward-vouchers","depth":2},{"value":"Listing reward vouchers","id":"listing-reward-vouchers","depth":3},{"value":"Applying a reward voucher","id":"applying-a-reward-voucher","depth":3},{"value":"Removing a reward voucher","id":"removing-a-reward-voucher","depth":3},{"value":"Troubleshooting (Voyado Specific)","id":"troubleshooting-voyado-specific","depth":2},{"value":"Error Codes","id":"error-codes","depth":3},{"value":"Links and References","id":"links-and-references","depth":2}],"frontmatter":{"seo":{"title":"Voyado Loyalty Adapter"}},"lastModified":"2026-04-28T10:46:59.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-portal/app-development/nco/adapters/voyado-loyalty-adapter","userData":{"isAuthenticated":false,"teams":["anonymous"]}}