--- language: "en" --- # K-Shop Merchant Documentation ## K-Shop Merchant Documentation Katalys provides embeddable K-Shops that allow anyone on the internet to purchase a product at the exact place where it was first seen. Katalys does not sell it... [Learn More](https://kb.katalys.com/shop/overview.md) ### Choose a Section * #### [Overview](https://kb.katalys.com/shop/overview.md) #### [For Publishers](https://kb.katalys.com/shop/publisher-tools.md) #### [For Merchants](https://kb.katalys.com/shop/merchant-integration.md) #### [Merchant Plugins](https://kb.katalys.com/shop/merchant-plugins.md) --- language: "en" --- # Katalys ⇢ Merchant ## From Katalys to the Integration When Katalys issues HTTP sends [Directives](https://kb.katalys.com/shop/directives.md) , the tokens are generated along the same guidelines as described in the [Katalys ⇠ Merchant](https://kb.katalys.com/shop/1o-merchant-1.md) section. Take the time to read that first. The following section will describe the same process from the opposite perspective, so a few key points will be repeated. In order to integrate with Katalys correctly, an integrator must verify that the requests are indeed coming from Katalys and have not been tampered with. We will now describe the authentication process from the perspective of an integrator (the receiver of the HTTP request). The authentication process is based on [PASETO](https://paseto.io/) tokens. We can't overstate how important it is to use an existing library (if available) to implement the process described in this section instead of implementing the algorithm yourselves. ## Step 1: Read the token HTTP requests sent by Katalys to integrators will include an `Authorization` header in the following format: `Authorization: Bearer TOKEN`. Let's look at an example: Authorization: Bearer v2.local.qwfi6mZ_xiom0Lz9dztkZ6p-_uXD06sb6DDHAe0UQbZbg7ESXD-h_izsciKQrR8P_WmrtQENAR4acJ0FEXpPUjEcUPwuYtYzKrqiS-naLkrNr-H2VWxDpQa8Zw2YtKBjM_aD.IntcImtpZFwiOlwiMGEzMTU2NjAtNGJiNy00MjI4LTk0MDgtZjQzMDA3MzMwNjZmXCJ9Ig In order to read the token we drop the `Bearer` prefix. What remains is a PASETO token: v2.local.qwfi6mZ_xiom0Lz9dztkZ6p-_uXD06sb6DDHAe0UQbZbg7ESXD-h_izsciKQrR8P_WmrtQENAR4acJ0FEXpPUjEcUPwuYtYzKrqiS-naLkrNr-H2VWxDpQa8Zw2YtKBjM_aD.IntcImtpZFwiOlwiMGEzMTU2NjAtNGJiNy00MjI4LTk0MDgtZjQzMDA3MzMwNjZmXCJ9Ig PASETO tokens consist of three or four segments (in our case we will be working with four) separated by a period: `version.purpose.payload.footer` ## Step 2: Verify version and purpose When decoding a token, we start by verifying the version and the purpose. The version must equal to `v2` and the purpose must equal to `local`. If the token does not match these two constraints we **must reject** the token as invalid. ## Step 3: Decode the footer The footer is a Base64-encoded JSON object. Continuing with the above example, the footer is: `IntcImtpZFwiOlwiMGEzMTU2NjAtNGJiNy00MjI4LTk0MDgtZjQzMDA3MzMwNjZmXCJ9Ig` After base64-decoding: `{"kid":"0a315660-4bb7-4228-9408-f4300733066f"}` This gives us the `kid` or the **key ID** . Using this value we can fetch the appropriate **shared secret**. *This mechanism allows us to have multiple keys, which in turn allows us to rotate the keys without downtime. It is very likely that at the start of the integration process you will only have a single key. It is still important that you verify that the key ID is correct.* ## Step 3: Verify the signature At this point we will repeat our mantra: you should use a PASETO library for this whole process, and especially for this step. Let's assume that in the previous step we fetched the following shared secret: `kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk` (secrets are 32 bytes long) If we pass the token and the shared secret to our library, we should be able to read the decoded payload: {"exp":"2023-11-03T14:50:30Z","iat":"2023-11-03T14:50:30Z"} `exp` is the Expiration time and `iat` is the Issued At time. We must verify that `iat` is in the past and that `exp` is in the future. This makes the token valid and authenticates the request. We can proceed servicing the request. ## Troubleshooting Certain shared hosting providers strip the `Authorization` header from incoming requests. ## See also [Example: generating a PASETO token](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1637384351) [Katalys ⇠ Merchant](https://kb.katalys.com/shop/1o-merchant-1.md) --- language: "en" --- # Katalys ⇠ Merchant ## From the Integration to Katalys The Sandbox Katalys GraphQL API is available at `https://shop.dev.katalys.com/graphql`. ## Authentication In order to access non-public resources, requests must be authenticated using [PASETO](https://paseto.io/) tokens. When generating a token you must satisfy the following requirements: * It must specify the `v2` version. * It must specify the `local` purpose. * It must have a **payload** containing at least an `exp` (Expiration) key and an `iat` (Issued At) key. For example: `{"exp": "2022-01-23T23:50:07Z", "iat": "2022-01-23T23:45:07Z"}` The above payload specifies that the token was issued on Jan 23rd, 2022 at 23:45 UTC and will expire on the same date at 23:50 UTC. Tokens are short-lived, so set the time to 5 minutes in the future (like in the example) or another reasonably short window. * Must have a **footer** containing a `kid` key, for example: `{"kid": "KEY_ID"}` where KEY_ID is the API **key ID** you received from Katalys. * Must be signed with the **shared secret** that you received from Katalys together with the key ID. To generate your first token, follow this guide: A token generated as described above must be passed as a bearer token in the `Authorization` HTTP header when making the request: Authorization: Bearer YOUR_GENERATED_TOKEN When the header is correctly set you should be allowed to make authenticated GraphQL requests. Here is an example request to access an order (select the fields that you actually need): GraphQL query Example { order(id: "008aef35-d31b-4340-a0ee-b25a3718a672") { id lineItems { id product { id title price } } } ## See also [Example: generating a PASETO token](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1637384351) [Katalys ⇢ Merchant](https://kb.katalys.com/shop/1o-merchant.md) --- language: "en" --- # Alternative option for enabling Apple Pay ## Self-Managed Apple Developer Account If placing a verification file is not possible, you can create your own Apple Developer Account. These are the basic steps, distilled from the Apple Documentation, for creating your own Developer account. *Prerequisites:* You must have an activated Apple Developer Account available. [Apple's documentation covers this process](https://developer.apple.com/support/app-account/) -- this guide will assume you already have access to an activated account. *Apple docs:* 1. You must receive a CSR from the Katalys Tech Team. 1. The CSR will must be generated via the Certificates API via Spreedly. 2. You submit it to Apple pay as CSR for Payment processing for Apple to sign it. This happens within seconds. 3. You submit the returned file to back to the Katalys Team. 4. You either repeat the above for merchant Id or submit the final version to us and do it themselves. 5. You must validate your own domain. 6. Apple Pay will now work natively on your domain. --- language: "en" --- # Authentication We suggest your read the overview first, then understand the role of the health-check directive and button. Only then proceed to actual implementation details. ## Overview Before Katalys's code and integrator's code can securely share messages. The following needs to happen: 1. Integration (as part of the initial setup) has to store credentials found in the Katalys platform. 1. integration ID 2. key ID 3. shared secret 2. Integration has to provide an endpoint (URL), which will receive messages coming from Katalys. The endpoint URL has to be stored in the Katalys platform → Settings → Apps \& Integrations →Integration → Settings There are **two** locations that require authentication to happen: ![KS Bridge.png](https://kb.katalys.com/__attachments/a_5fd3076b1e964978ce66bce72b5421b90756fdb117e9f7006fbbed48cf569333/KS%20Bridge.png?cb=da3552a583405ff8994a7b5d2ab7a2f1) 1. When Katalys platform sends directives to the integration. Katalys ⇢ Merchant 1. Katalys platform creates a token and sends a request with directives 2. **Integration** receives the request and verifies the token before processing the directives 2. When the Integration sends API requests to Katalys. Katalys ⇠ Merchant 1. **Integration** generates a token using stored credentials and adds it to request header before sending the request to the API. 2. Katalys's API will verify the token and process the request ## Health-check directive Health check is triggered from Katalys platform's UI. It will send a health-check directive payload with a token to the integration's URL. The integration is expected to verify the token first, then proceed to generate a token and make an authenticated request to Katalys's API. If all of the above succeeds, we can consider the two systems connected. ![Untitled.png](https://kb.katalys.com/__attachments/a_432df9f7225b7dea76414491b29756e3773012b634191188d36e80e1cda06e70/Untitled.png?cb=7b684fb8a162865dcc9d899add3b12f5) ## Next steps [Katalys ⇠ Merchant](https://kb.katalys.com/shop/1o-merchant-1.md) [Katalys ⇢ Merchant](https://kb.katalys.com/shop/1o-merchant.md) [Example: generating a PASETO token](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1637384351) --- language: "en" --- # Build a Custom Integration The Katalys platform provides a bridge from User and Consumer actions into the Merchant's CRM. This means the merchant must have an endpoint that can receive events from Katalys. ![Katalys Shop Basic Merchant Overview.png](https://kb.katalys.com/__attachments/a_6d5cd7f41b9518a2ffab8e9401dc5456b5cee87116f8c69b0521869470b76a87/Katalys%20Shop%20Basic%20Merchant%20Overview.png?cb=aac56383cfbc12bbb057ea8d0a17e16f) Overview of an example Merchant Integration This documentation focuses on the interaction between **Katalys** and a **merchant** . First, it provides an overview of all the pieces and how they are linked. Then, it explains how to get started by setting up a test environment. Finally, it goes into **technical details** of how to integrate Katalys with a merchant's e-commerce stack. ## What are the goals of Katalys-to-Merchant integration? 1. Products selling on merchant's store can be automatically turned into Katalys Shops. 2. Purchases made with Katalys Shops are automatically inserted into the merchant's store as if the purchase happened in the store itself. ### Integrator Integrator is the developer, capable and responsible for building the bridge(integration) between Katalys and the Merchant's stack. ## The pieces ![KS-Bridge-20230817-115616.png](https://kb.katalys.com/__attachments/a_36ec3521964527152fec219884cfc066f4dc6d97bebe8ff0b93efe4fd0ca9912/KS-Bridge-20230817-115616.png?cb=27448c4333103bf0b5ed74ac1badc313) The area in pink is what the integrator needs to build. The area in pink is what the integrator needs to build. **Katalys Shop** - customers buy products in the Katalys Shop, and the Katalys Shop communicates with the Katalys Platform **Katalys Platform** - merchants will manage Shops and orders in the Katalys Platform, the Platform sends [Directives](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1637613663) to the Katalys-to-Merchant Integration and it provides an API to communicate with **Merchant's Stack** - represents the Merchant's store that contains products to be turned into Katalys Shops, and that will receive orders **Katalys-to-Merchant Bridge(Integration)** - This is the code responsible to receive directives from Katalys Platform, communicate with Katalys' API and communicate with Merchant's store either via API or direct access to code. This is the **integrator's responsibility** to develop. ## Integrator's plan 1. [Test environment](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1637515348) setup. 2. [Authentication](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1638006806) and connectivity. 3. [Directives](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1637613663) drive every operation. 4. [Importing products](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1636991046) and checking the result. 5. [Order processing](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1638072337) and completion. --- language: "en" --- # Completion Once you're confident the integration is ready for an actual live store. Let's make sure we all understand what does it take to install and use. This might prompt building additional documentation and instructional videos. --- language: "en" --- # Coupon discount for free shipping You can add a coupon to give free shipping for the Katalys platform. This coupon won't be available to use in your store. This coupon won't be able to give a discount, will give only free shipping. ## **How can You add the coupon?** The menu by side click in **Marketing -\> Coupons**: ![image-20231201-021924.png](https://kb.katalys.com/__attachments/a_d0f250aadea08ba4b26638f6f536f57498fbe8f67d2a1a7c1c932621ff5ee02e/image-20231201-021924.png?cb=032b8aec2a8836d6d4c180ddf63ac6cd) Click on the Add coupon: ![image-20231201-022001.png](https://kb.katalys.com/__attachments/a_50535da9eaee7dcb7c561db31f2490658385b0aeecb0a4d02f986396b8a06909/image-20231201-022001.png?cb=3a5464e02c16507579a5e11cb611865c) After that, you need to put a Coupon code. The coupon code needs to start with the prefix **KS_** to work and select **Allow free shipping**: ![image-20231201-022108.png](https://kb.katalys.com/__attachments/a_046254d3a1df04d44ef001a226240e341ef672faffe4f2c35b80b3fd584ba0ef/image-20231201-022108.png?cb=fc32c8c320ee481fb626b050677e17b9) If you don't put the prefix KS_ and select **Allow free shipping**, won't work correctly. If you try to use the coupon in your store, will happen the error below: ![image-20231201-022138.png](https://kb.katalys.com/__attachments/a_21cd95f757e2368c0b3f732eb08ca837677033037dee2f05961c3359c29c8935/image-20231201-022138.png?cb=2353c8a8c7254d96c004da69a73a146e) After you create a coupon, will be available automatically to use via the platform. The platform will show only free shipping if you create the coupon, and won't show others shipping rates. After you add the coupon, when you have an order with the coupon, you will see the order equal below: ![image-20231201-022212.png](https://kb.katalys.com/__attachments/a_7c0487da1a9ba3571fa842b713ae674e8653e80a7bab0208f441ed2fc349ce54/image-20231201-022212.png?cb=26b0d2da39711d239abd11cc047db662) The feature above is available in version **1.1.15** or more. --- language: "en" --- # Free-Shipping Coupon You can add a discount coupon as a way to offer free shipping. This coupon will not be available to use on your store front and will only be available in the form of *free shipping*. ## **How to add the coupon?** ### 1. Navigate to Cart Price Rules From the side navigation menu, select: **Marketing → Promotions → Cart Price Rules** ![image-20231215-120255.png](https://kb.katalys.com/__attachments/a_9e2dcbddfcd748859b082a7f283cd63b6d6ca8cc9ffe33cfcb4293f9a13587de/image-20231215-120255.png?cb=ba3d681192be0013ba319dc5776da8df) #### 3. Click on Add New Rules: ![image-20231215-120414.png](https://kb.katalys.com/__attachments/a_b5d28d6226e317346e36e878eaed19c0f7a802e9d367b8f73e657f0de98b7859/image-20231215-120414.png?cb=fc26454c162fac8b21a31fea2017bdac) #### 4. Set the Coupon Code Next, set a coupon code. To set it, you must use the prefix `KS_`, ultimately selecting the field **Free Shipping** option **For matching items only.** See below setup flow: ![image-20231215-120943.png](https://kb.katalys.com/__attachments/a_5e981f4496fe0d14ab0e9ded6b8bda83522ea4dc80ebd6cedcaf418f200eb055/image-20231215-120943.png?cb=4daef1ee925c21f3fe38c302fd241fc6) ![image-20231215-121600.png](https://kb.katalys.com/__attachments/a_f566dec769e9b65e8dc46a1e512ef4aee497ecdf75cf3fcea567da9e3a131faa/image-20231215-121600.png?cb=86322bcc58ce2df35b2a993a0e2bae8a) ![image-20231215-121017.png](https://kb.katalys.com/__attachments/a_ef5683a97489ee9b214300335e4c8c31ceb8e8ba3d27ea6edd151a6586e28538/image-20231215-121017.png?cb=e34b396592393d836b5af00c2bc1dc07) ![image-20231215-121031.png](https://kb.katalys.com/__attachments/a_deaf07b8c8b6b985812bec12e981cb73ef252158e5fb702292a32ed8fae7b1d3/image-20231215-121031.png?cb=5eadffdbf60108ec86e9bc7991a3e7a5) #### 5. Create the Coupon Create the coupon using basic information (above), as is required ( Magento will not apply ). After creating a coupon, it will be automatically available for use within the platform. Note that the platform will only show free shipping when a coupon is created for that, without revealing shipping rates ( see below example ) : ![image-20231215-121846.png](https://kb.katalys.com/__attachments/a_37d3719c58dc60ebada568589d7780532d2ba92f793f387c0c170123750764fe/image-20231215-121846.png?cb=65522f77c2710f194a6b29d5efd095d2) #### 6. Applying the Coupon After adding the coupon, when an order applied the coupon, you will see the order, as shown below: ![image-20231215-121946.png](https://kb.katalys.com/__attachments/a_2cd08733ad1efd311cde7abd56e69fdfd2284be4c2c094273b6eda65786f258c/image-20231215-121946.png?cb=b04f533066601a04e353dc3de75b433b) Note: The free shipping coupon is not available on the store front - see below example: ![image-20231215-122137.png](https://kb.katalys.com/__attachments/a_f2b924c1a348226ac744d8cd070d08927df24ea3b66b740a41f52231307051fa/image-20231215-122137.png?cb=0bdf45772d15edb082f1d12bf32b4293) --- language: "en" --- # Data Models: Order, LineItem, and Transaction The following is an overview of the relevant data models provided by the Shop. ## Order Model { "paymentStatus": "paid", "customerName": "John Doe", "customerEmail": "dev@1o.io", "customerPhone": "+123456789", "billingName": "John Doe", "billingEmail": "dev@1o.io", "billingPhone": "+123456789", "billingAddressLine1": "Example address 132", "billingAddressLine2": "Apt. 4", "billingAddressCity": "Los Angeles", "billingAddressState": "CA", "billingAddressZip": "90002", "billingAddressCountry": "United States", "merchantOrganizationId": "3e90434d-9338-4356-8676-e7d99623a3ae", "shippingName": "John Doe", "shippingEmail": "dev@1o.io", "shippingPhone": "+123456789", "shippingAddressLine1": "Example address 132", "shippingAddressLine2": "Apt. 4", "shippingAddressCity": "Los Angeles", "shippingAddressZip": "90002", "shippingAddressCountry": "United States", "storefrontId": "af59a33d-e5c2-47fd-98a7-2151f6dda571", "fulfillmentStatus": "waiting", "totalPrice": 1200, "totalTax": 114, "totalShipping": 500, "total": 1814, "currency": "USD", "lineItems": [ { "productId": "b6a3faa7-14a1-4629-b97e-9d7b62be8532", "variantId": "b06676ee-f10b-4d23-8462-f2dd0c8c6f41", "productMerchantData": "{\"RevOffersOrderMeta\":\"abcd-1234-efgh\"}", "variantMerchantData": "{}", "sku": "123456", "name": "Fashion Police Pink S", "imageUrl": "https://i.imgur.com/f6yn2DE.jpg", "details": "Fuchsia Pink • S", "quantity": 1, "price": 1200, "tax": 114, "total": 1314, "currency": "USD" } ], "transactions": [ { "name": "Stripe charge", "total": 1814, "currency": "USD", "gatewayData": "{\"id\":\"pi_3JpvQHIj7KMjryuv2N0jTGuR\"}", "succeeded": true } ] } | Variable | Value | Description | |------------------------|---------------------------------------------|------------------------------------------------------------------| | storefrontId | String | Katalys internal ID of shop where order occurred | | merchantOrganizationId | String | Katalys internal ID of merchants organization | | paymentStatus | String(paid, pending, refunded or rejected) | Status of the payment for the order. | | customerName | String | Full name of the customer | | customerEmail | String | Email of the customer | | customerPhone | String | (Optional)Phone number of the customer | | billingName | String | Billing persons Full Name | | billingEmail | String | Billing persons Email | | billingPhone | String | (Optional)Billing persons Phone | | billingAddressLine1 | String | Billing persons Address Line 1 | | billingAddressLine2 | String | (Optional)Billing persons Address Line 2 | | billingAddressCity | String | Billing persons City | | billingAddressState | String | Billing persons State | | billingAddressZip | String | Billing persons Postal Code | | billingAddressCountry | String | Billing persons Country | | shippingName | String | Shipment recipient: Full Name | | shippingEmail | String | Shipment recipient: Email | | shippingPhone | String | (Optional)Shipment recipient: Phone | | shippingAddressLine1 | String | Shipping addres: Address Line 1 | | shippingAddressLine2 | String | (Optional)Shipping addres: Address Line 2 | | shippingAddressCity | String | Shipping addres: City | | shippingAddressState | String | Shipping addres: State | | shippingAddressZip | String | Shipping addres: Postal Code | | shippingAddressCountry | String | Shipping addres: Country | | fulfillmentStatus | String(fulfilled, waiting or cancelled) | Status of the fulfillment | | totalPrice | Integer | Total price of the products(quantity \* products price) in cents | | totalShipping | Integer | Total shipping cost of the order in cents | | totalTax | Integer | Total charged tax in cents | | total | Integer | Total amount charged | | currency | String(ISO 4217) | Currency of the order | | lineItems | LineItem | Information about ordered goods | | transactions | Transaction | Information about all connected transactions | ## LineItem Model { "productId": "b6a3faa7-14a1-4629-b97e-9d7b62be8532", "variantId": "b06676ee-f10b-4d23-8462-f2dd0c8c6f41", "productMerchantData": "{\"RevOffersOrderMeta\":\"abcd-1234-efgh\"}", "variantMerchantData": "{}", "sku": "123456", "name": "Fashion Police Pink S", "imageUrl": "https://i.imgur.com/f6yn2DE.jpg", "details": "Fuchsia Pink • S", "quantity": 1, "price": 1200, "tax": 114, "total": 1314, "currency": "USD" } | Variable | Value | Description | |---------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| | productId | String | Katalys internal ID of shop where order occurred | | variantId | String | Katalys internal ID of merchants organization | | productMerchantData | String | (Enabled upon request) (Optional) Stringified JSON. Data added on product import provided by merchant - intended for their unique data(eg. attribution system) | | variantMerchantData | String | (Enabled upon request) (Optional) Stringified JSON. Data added on variant import provided by merchant - intended for their unique data(eg. attribution system) | | sku | String | (Optional) SKU of the item | | name | String | Name of the variant | | imageUrl | String | URL to the main image of the item | | details | String | Information about selected option | | quantity | Integer | Amount of specific item ordered | | price | Integer | Price of the item in cents | | tax | Integer | Tax for the item in cents | | total | Integer | Total cost of the item in cents | | currency | String(ISO 4217) | Currency of prices | ## Transaction Model { "name": "Stripe charge", "total": 1814, "currency": "USD", "gatewayData": "{\"id\":\"pi_3JpvQHIj7KMjryuv2N0jTGuR\"}", "succeeded": true } | Variable | Value | Description | |-------------|---------|-----------------------------------------------------------------------------------------------------| | name | String | Name of transaction and it's processor | | total | Integer | Amount processed in transaction in cents | | currency | String | Currency of the transaction | | gatewayData | String | Stringified JSON with additional data. Will always posses id of the transaction inside the platform | | succeeded | Boolean | True if transaction successfully completed | --- language: "en" --- # Directives When processing an order, the Katalys Platform might issue what we call *directives* . These instruct an *integration* to perform certain tasks, usually related to orders and products (checking product availability, calculating order tax, ...). Integrators might be familiar with the concept of webhooks---this is the model that directives are largely based on, with the main difference being that we only expect the integration to offer a single HTTP endpoint that will receive JSON payloads from the Katalys Platform. A payload might include multiple directives and each directive might reference a different entity in the system. This is why each directive in the payload includes its own arguments, even though they might repeat: JSON { "directives": [ { "id": "d3cca723-6317-4fdf-8ccd-9a0ca10aff77", "directive": "update_availability", "args": { "order_id": "44f13c01-3f72-4096-9abc-d9bae86e2ef2" } }, { "id": "24ab1e15-5681-4a05-9987-2a413ef4dd6b", "directive": "update_available_shipping_rates", "args": { "order_id": "44f13c01-3f72-4096-9abc-d9bae86e2ef2" } }, { "id": "a2b9c1df-5caf-4785-a37b-6d6f38a177e8", "directive": "update_tax_amounts", "args": { "order_id": "44f13c01-3f72-4096-9abc-d9bae86e2ef2" } } ] } Directives should be processed in order. There is no need to attempt to optimize the process by attempting to satisfy multiple directives at once or share data between them. ## Robust processing and error handling The most important part (aside from satisfying the directives themselves) is to service the request in a robust manner, such that a failure in processing one of the directives is correctly signaled in the response and does not cause request processing to fail with a 500 server error. Notice how we handle errors, collect the error message and error's backtrack. Ruby results = [] directives.each do |payload| result = { source_id: payload.id, source_directive: payload.directive } begin result.merge!({ status: "ok", data: process_directive(payload) }) rescue e result.merge!({ status: "error", data: { message: e.message, trace: e.backtrace } }) end results.push(result) end JSON.dump({ results: results }) Following the above ruby snippet, the resulting response could look like this: Notice how a failed directive is sent back with error details. Please implement the same structure. You're free to add additional fields to the details object and help yourself address crashes. JSON { "results": [ { "source_directive": "update_availability", "source_id": "ee4d346f-de86-4285-934c-a9f1b9c5c0ed", "status": "ok" }, { "source_directive": "update_available_shipping_rates", "source_id": "45a42385-8ebd-45bb-9ac8-c7365aa157ac", "status": "ok" }, { "source_directive": "update_tax_amounts", "details": { "message": "[TEST] simulate_error_reporting_health_check", "trace": [ "lib/shopify_app_web/controllers/oneo_to_merchant_controller.rb:61", "lib/shopify_app_web/controllers/oneo_to_merchant_controller.rb:33", "lib/phoenix/router.ex:354" ] }, "source_id": "6e1efe64-2f37-40c4-8198-c8b7827dba5d", "status": "error" } ] } ## Next steps [Importing products](https://kb.katalys.com/shop/importing-products.md) [Order processing](https://kb.katalys.com/shop/order-processing.md) --- language: "en" --- # Enabling Apple Pay Apple Pay is the preferred method of accepting payment within your Shops. Apple Pay is seamless -- it provides the best experience for your visitors and the easiest flow for your customers. We recommend enabling Apple Pay for all your Shop deployments. ## Scope of Work Activating Apple Pay is straight-forward. **Decide which domain to verify.** The Apple Pay feature must be activated per-domain. If you intend to use Shops on multiple subdomains, we recommend activating the "Top-Level Domain" (TLD) for your website; this means, to use Apple Pay for Shops on `shop.mywebsite.com` and `www.mywebsite.com`, you need to verify the TLD `mywebsite.com`. If you intend to use the shop on just one subdomain, such as `www.mywebsite.com`, then you should activate the exact-match domain `www.mywebsite.com`. **Decide whether you or Katalys will perform the verification.** To perform the verification, you must have a registered and activated Apple Developer Account. We recommend that Katalys manage this process for you. You might decide to use the [alternative self-managed approach](https://katalys.atlassian.net/l/cp/3CjxRueL)if you are already using an Apple Developer Account features on your domain. Confirm with your development team if you have Apple Developer features in-use on your domain. **Be aware of timeline.** The domain will remain verified until the expiration of the SSL certificate. You will not need to re-verify your domain until the SSL certificate is about to expire. If you are using a single account to verify your domain, then simply leave the file in place and Apple will automatically perform this verification for you -- no further action required. Your Katalys representative will notify you when verification is about to expire. ## Katalys-Managed Apple Developer Account Katalys can manage and maintain an Apple Developer Account. Using this easy-to-follow guide, Katalys will offer you simple steps to activate Apple Pay for your shops. 1. Alert Katalys that you would like Katalys to activate your domain. The Katalys Tech Team will kick-start the verification process. 2. Your Katalys representative will forward you a file generated in the verification process. You must place this file on your domain, with no redirects, at the following path: `https://{your-domain}/.well-known/apple-developer-merchantid-domain-association.txt` 3. After having placed the file, alert your Katalys representative that the file has been deployed. Katalys will proceed with the verification. 4. After completion, your Katalys representative will tell you it is now safe to activate Apple Pay on your Shops. That's it! If you use multiple Apple Developer Accounts, be aware that you can verify your domain multiple times by changing this file for each verification. The verification will last until your SSL certificate renews. However, if you leave this file in place, you can continue to accept Apple Pay indefinitely. --- language: "en" --- # Enabling Free Shipping "Override" For Products You are able to offer Free Shipping for transactions made through the K-Shop via a simple configuration within your CRM. This feature overrides whatever shipping cost is calculated by your CRM, so there is no need to create a new CRM product with Free Shipping, in order to offer free shipping through K-Shops. Please follow the instructions for the appropriate CRM platform: * [Salesforce](https://kb.katalys.com/shop/shipping-promotions) * [WooCommerce](https://kb.katalys.com/shop/woocommerce-enabling-free-shipping-override-within) * [Magento](https://kb.katalys.com/shop/magento-coupon-discount-for-free-shipping) * BigCommerce (Coming Soon!) * Shopify (Coming Soon!) --- language: "en" --- # Error Reporting Healthcheck Error Reporting Healthcheck should be the first directive to implement. Why? 1. You can trigger it by clicking a button and see feedback in real time. ![image-20230929-115104.png](https://kb.katalys.com/__attachments/a_3ef2440ced06ca46cf281ac6153b5db57be69b49a37662d9b6d780cd4b882609/image-20230929-115104.png?cb=6301831642c81c8a9968e323f5b4ea1b) 2. It's quite handy to receive real time feedback with error details when you implement directives. By implementing this directive you'll understand how to leverage existing tools and help yourself when the integration your're developing crashes. 3. With the directive implement we can verify for each client that error-reporting works and that we'll be notified on crashes Before implementing a directive implement the processing loop. Expected Payload: { "directives": [ { "args": {}, "directive": "simulate_error_reporting_health_check", "id": "19ea7e1b-c8f7-4c82-b9de-32035675fbfa" } ] } Expected Response: { "results": [ { "details": { "message": "[TEST] simulate_error_reporting_health_check", "trace": [ "lib/shopify_app_web/controllers/oneo_to_merchant_controller.ex:61", "lib/shopify_app_web/controllers/oneo_to_merchant_controller.ex:33", "lib/phoenix/router.ex:354" ] }, "source_directive": "simulate_error_reporting_health_check", "source_id": "19ea7e1b-c8f7-4c82-b9de-32035675fbfa", "status": "error" } ] } Reference Implementation (Elixir): Elixir defp directive(_store, "simulate_error_reporting_health_check", _args) do raise RuntimeError, message: "[TEST] simulate_error_reporting_health_check" end Once Katalys receives a correctly structured error response it will: 1. Report to internal error collector tool ![image-20230929-115843.png](https://kb.katalys.com/__attachments/a_27d2d6f0ef60dd4158e60f8198ee8c16d08254339e3f7c1557cf9e1b2283c5e1/image-20230929-115843.png?cb=e7aa86ee3b502786e2e168da439ca5ff) 2. Notify Katalys engineers ![image-20230929-115906.png](https://kb.katalys.com/__attachments/a_a232b0e15f0350693e25fb0d81f8e3e1fdc7f6613faf1063d9ea1444975e2755/image-20230929-115906.png?cb=20d3daae929645981fcc489e20078f1a) --- language: "en" --- # Example: generating a PASETO token Follow this guide step by step to make sure that your tokens are correctly generated. As specified in the [Katalys ⇠ Merchant](https://www.notion.so/1o-Merchant-f6e45fbd464f4591993ead4afbfaa39d) page, the Katalys API will accept (and in some cases, expect you to generate) `v2.local` tokens. For this example we will assume the following payload, key ID, and shared secret: * **Payload** JSON {"exp":"2023-11-03T14:50:30Z","iat":"2023-11-03T14:50:30Z"} * **Shared secret** kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk (The letter `k` repeated 32 times.) * **Footer** JSON {"kid":"0a315660-4bb7-4228-9408-f4300733066f"} Now we have everything we need to generate a token using the PASETO library of our choice. Passing all of the above should yield a valid token: JavaScript version = 'v2' purpose = 'local' payload = '{"exp":"2023-11-03T14:50:30Z","iat":"2023-11-03T14:50:30Z"}' shared_secret = 'kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk' footer = '{"kid":"0a315660-4bb7-4228-9408-f4300733066f"}' generate_paseto_token(version, purpose, payload, shared_secret, footer) // token: 'v2.local.R17UZaSjwDIOVGvfPfpZl3ff5mUOViu0we2uutl9VKSxyxCz_XlECXiolPl3Yh1A-lcfNQAYTb4-BiGQXCMP5SNa5yUrTyiy_kwFrLaV0pi2Q-6LZwPJdgX_mrnBS2OrOkdZ.IntcImtpZFwiOlwiMGEzMTU2NjAtNGJiNy00MjI4LTk0MDgtZjQzMDA3MzMwNjZmXCJ9Ig' Use the above values to verify token generation. Using the exact inputs should yield the same token. *** ** * ** *** *For maintainers: When updating the tokens in this guide consult this* [*code snippet*](https://gist.github.com/mfilej/b400f83f6828c2fe17d5ce92a429171d)*.* --- language: "en" --- # External IDs In order to allow integrations to persist information on which Katalys entities are related to which entities on the integration side we offer the concepts of *external IDs* and *external data*. ## Products External IDs can be retrieved with GraphQL queries on products: JSON { product(id: "44ad5ce9-9c3f-43c5-afab-d0796269d68c") { externalId } } JSON { "data": { "product": { "externalId": "14" } } } If a product with an external ID is purchased (through the Katalys checkout process) the resulting order's line item will reference the external ID (the following example assumes that the variant's external ID is 99): GraphQL { order(id: "235c9162-80c2-4fd4-9eb8-e398ed130329") { lineItems { productExternalId variantExternalId } } } JSON { "data": { "order": { "lineItems": [ { "productExternalId": "14", "variantExternalId": "99" } ] } } } ## Orders Similarly, orders can store external IDs as well. Additionally, they can store *external data*. This is a field that can store a given JSON. This allows you to treat the Katalys API as a database and store any metadata you might need for your integration. GraphQL mutation M($id: ID!, $externalId: String, $externalData: JsonString) { updateOrder(id: $id, externalId: $externalId, externalData: $externalData) { id externalId externalData } } JSON // variables { "id": "235c9162-80c2-4fd4-9eb8-e398ed130329", "externalId": null, "externalData": "{\\"myField\\":\\"just an example\\"}" } JSON // result { "data": { "updateOrder": { "externalData": "{\\"myField\\":\\"just an example\\"}", "externalId": "myid-123", "id": "235c9162-80c2-4fd4-9eb8-e398ed130329" } } } In order to allow unstructured objects to be passed in `externalData` we have to encode the JSON as a string. --- language: "en" --- # Healthcheck Health check should be the first directive to implement. Why? 1. You can trigger it by clicking a button and see feedback in real time. 2. This is quite handy when implementing: [Authentication](https://kb.katalys.com/shop/authentication.md) Before implementing a directive implement the [Directives](https://kb.katalys.com/shop/directives.md) processing loop. Expected Payload: JSON { "directives": [ { "directive": "health_check", "args": {}, "id": "030fe55d-abd9-4ad5-b8c9-690549d9abec" } ] } Minimal Required response: JSON { "results": [ { "data": { "healthy": true, "internal_error": null, "public_error": null, }, "source_directive": "health_check", "source_id": "030fe55d-abd9-4ad5-b8c9-690549d9abec", "status": "ok" } ] } Failing healthcheck: JSON { "results": [ { "data": { "healthy": false, "internal_error": "Something to help debugging.", "public_error": "Your store is not working properly", }, "source_directive": "health_check", "source_id": "030fe55d-abd9-4ad5-b8c9-690549d9abec", "status": "ok" } ] } Richer Response: JSON { "results": [ { "data": { "healthy": true, "implemented_directives": [ "health_check", "update_available_shipping_rates", "update_tax_amounts", "update_availability", "complete_order", "import_product_from_url" ], "internal_error": null, "name": "Katalys Shopify integration", "public_error": null, "version": "6edbd0b" }, "source_directive": "health_check", "source_id": "030fe55d-abd9-4ad5-b8c9-690549d9abec", "status": "ok" } ] } --- language: "en" --- # How to Embed Katalys Shops (Pop-up, Tray) **Please note:**To function properly, Katalys Shop links require that you are able to place a line of JavaScript into your page header (directions below). If you are prohibited from doing so for any reason, please notify Katalys with whatever information you may provide that details your constraints, so that we can begin the proper discussions with your organization. *This page describes how to embed a Katalys Shop link in a webpage, with a test Katalys Shop provided to help you identify any potential issues well in advance of activation within your website.* ## ++Overview++ Embedding a Katalys Shop requires the placement of two elements: * a `katalys.shop/js/1o` tag within your page header, and * a Katalys Shop embeds within your page content. Here is how to validate that this integration will work with your website: ### **Step 1 of 4: Place the Header Script** Place the katalys.shop.js tag below between the \ and \ tags of your website HTML. ### **Step 2 of 4: Place the Shop Link** Insert this link to any clickable asset like text, image, or button to open the Katalys Shop in a pop-up from the clickable asset. CLICK ME:) The Shop appears similar to this example, in pop-up format: ![image-20221024-161846.png](https://kb.katalys.com/__attachments/a_77e69839064a84629b3f005dc9109300fc0255ebc88fb933bd25a883365398d8/image-20221024-161846.png?cb=37d251c10cf0f150a0a7cbe57377f692) Once the link has been inserted, you can validate if the embedded iFrame is behaving correctly in the following steps. ### **Step 3 of 4: Visual Confirmation** On a desktop device, when you click the hyperlinked text `CLICK ME:)` you should see the Katalys Shop open as a modal on top of the page content. It should *not*open in a new browser window. *This looks correct:* ![image-20220908-185528.png](https://kb.katalys.com/__attachments/a_141681a01c5643950cd335e86b39fccb5e7d8acd7299f07b9cc412efafebc9d2/image-20220908-185528.png?cb=cac2d4b3f9bb4472dcb93e8bc3a8f73c) *Note the following correct qualities:* * On desktop, the Katalys Shop opens as a modal popup on top of your page content. *This looks incorrect:* ![image-20220908-185546.png](https://kb.katalys.com/__attachments/a_ae609a6000fb3a811194b79553ab2897bdb9d7a53dc0e5a6bf66253f6f434969/image-20220908-185546.png?cb=4f5ef96487d241f2de9d5c50edcea103) *Note the following incorrect qualities:* * When you click on the text that is hyperlinked to the Katalys Shop, the Shop opens in a new browser window, rather than as a modal popup on top of your page content. ### **Step 4 of 4: Test Your Link** Our online testing utility is currently under construction. Please contact Katalys to assist in final checks to validate that your Katalys Shop links are functioning as expected. ## ++Appendix:++ ## What is a Katalys Shop Link? A Katalys Shop is an embeddable checkout component enabling the purchase of a product, using the merchant's e-commerce stack technology, from within a 3rd-party website or application. --- language: "en" --- # How to Embed Katalys Shops (In the line) **Please note:** Embedded inline Katalys shops **DO NOT** require JavaScript installation. Katalys shops will be displayed within the content like YouTube videos. JavacSript is required only for pop-up (overlay) and tray display modes. Please refer to [**this article**](https://kb.katalys.com/shop/how-to-embed-1o-shops) to learn more about how to set up Katalys Shops for Pop-up and Tray display mode. Embedding Katalys Shop in the conectent is as easy as embedding YouTube a video. Follow a few simple steps below: ## **Step 1: Open Katalys Shop Builder** Shop builder is an advanced and easy to use editing tool that let's users customize, optimize and tailor Katalys shops to fit any page. Shop builder can be launched from Katalys Shops Admin or directly via URL. ![image-20240130-084252.png](https://kb.katalys.com/__attachments/a_fc53c846a3d6832ff14bcfbedebbc4bfdfb7261a05edab423bb833cb93996ca0/image-20240130-084252.png?cb=c7931fd1f03e17872df5167bb5d19e04) ### **Step 2: Select Inline Display Mode** In Katalys Shop Builder panel select Inline Display mode to display Katalys Shop as an embedded widget inside the content (like YoutTube video). ![image-20240130-084505.png](https://kb.katalys.com/__attachments/a_f9b39152e1f21abf518a233994f5dd359c4acc52c0e094c8b23fb4cf910a1733/image-20240130-084505.png?cb=f499d05732206b30d065452dadb411ab) ### **Step 3: Copy the Inline Shop Embed Code and paste it to your preferred content editor** Click the **Embed button** in the top right corner to open the right drawer. Copy the embed code below and paste it in to your preferred editor. You are done! ![image-20240130-085401.png](https://kb.katalys.com/__attachments/a_a493b11b1b67bde4b987a42ced51cea8ed3a0784e158497eb8b69a3cd1f92395/image-20240130-085401.png?cb=f1abb4aa8fe8a9420a1832018439f48c) ### **Step 4 (optional): Customize your shop** Use Shop Builder advanced features to customize shop's appearance, add tracking and custom branding. Learn more about Shop Builder [here](https://kb.katalys.com/shop/katalys-shop-builder-embedding-instructions.md). ## **Embed a Katalys Shop (native unit) into a WordPress Post** Embedding a Katalys Shop into your content is as easy as embedding a Youtube video. Simply paste the code and your Katalys Shop will appear in your content. Here's how: 1. Log in to your WordPress **Admin Dashboard**. 2. Select **Posts** in the left-hand menu. 3. Select **Add New** to create a new post or select and edit an existing post from the **All Posts** list. 4. If you are using **Block Editor** , select the "**+**" icon where you would like to place your Katalys Shop within your content. 5. Select the **\[ / \] Short Code** option or the **Custom HTML** option from the Block Shortcut dropdown. If the option isn't there, click search for Short Code or click the **Browse All** button. The Blocks menu will open on the left. Search for **Short Code** or **Custom HTML** or simply scroll down to the **WIDGETS** section. 6. **Paste** the embed code in the input field. 7. Click **Preview** , **Save draft,** or **Publish**. 8. And you're done! Check out your Katalys Shop on your site to make sure it's working properly. --- language: "en" --- # Importing Products ## Triggering `import_product_from_url` from the UI Preconditions 1. You have [Setup Test Environment](https://kb.katalys.com/shop/test-environment.md) 2. You created a Store (Integration) and implemented [Authentication](https://kb.katalys.com/shop/authentication.md) 3. The Store you're importing from is Healthy and Enabled 1. Verify by visiting the stores's edit screen. (Settings, Stores, Store) Steps 1. Click on "Products" - left menu 2. Click on "Import" - button, top right 3. You are presented with Stores you can import products from 4. Paste product URL into the input box and 5. Navigate to settings, stores, the store you're developing for 6. See the directive in logs ## Servicing the `import_product_from_url` directive A Katalys platform user wants to import a new product from the Merchant's store. JSON // POST { "directives": [ { "args": { "product_url": "https://mertchants-store.com/products/some-product-id" }, "directive": "import_product_from_url", "id": "47e92567-e45f-4f35-a0e3-4d6322340c82" } ] } ### Success response "result" (line 4) below should contains **Katalys' product ID**. { "results": [ { "result": "042bd63f-02d2-43d2-8446-46f0a12ce076", // katalys product id "source_directive": "import_product_from_url", "source_id": "47e92567-e45f-4f35-a0e3-4d6322340c82", "status": "ok" } ] } ### Error response Set the the status to "error" and write your own error message. { "results": [ { "error": "Unusable URL: https://unusable.com/products/wrong", "source_directive": "import_product_from_url", "source_id": "47e92567-e45f-4f35-a0e3-4d6322340c82", "status": "error" } ] } Use the received `product_url` to work out which product to import. Ideally we'd like to be able to process public product pages, so a Katalys platform user can just grab a public url and turn it into a functional Katalys shop. This does not mean you should be scraping data from the public page, but identify the product and import it properly. For example in some integrations we support importing from a public page and an admin page. ### Creating the product GraphQL mutation Create($input: ProductInput!) { createProduct(input: $input) { id } } Below we specify an example of how variables for the above mutation can look like. It is important to understand the following concepts: * A product can have zero, one, or many *variants*. * When a shop offers a product with variants, a buyer will only be able to purchases one of the variants --- never the *parent product*. The Checkout flow preselects a variant and the buyer is able to switch between the rest of the variants. * Both variants and products share the same attributes and are represented with the `Product`. During the checkout process, a variant inherits attributes from the parent product. Therefore the variant only needs to specify values that make it different from the parent product. * The `external_id` attribute is free form text and it's your decision what to put in there, it should allow you to find the product/variant in the merchant's store * `option_names` is present on the product and defines available options for the user to chose from. * `option_1_names_path` and `option_2_names_path` are present on the variant and define which options need to be selected for the variant to be chosen. Example variables for the `createOrder()` input value. JSON { "input": { "name": "Intenal prduct name", "title": "Public product title", "currency": "USD", "currency_sign": "$", "price": 120, "compare_at_price": 140, "summary_md": "### Short product summary", "summary_html": "

Short product details

", "details_md": "### Long product details", "details_html": "

Long product details

", "external_id": "p1", "shop_url": "", "images": [ "", "" ], "option_names": [ { "name": "Color", "position": 1, "options": [ { "name": "Pink", "position": 1 }, { "name": "Yellow", "position": 2 } ] }, { "name": "Size", "position": 2, "options": [ { "name": "L", "position": 1 }, { "name": "M", "position": 2 } ] } ], "variant": false, "variants": [ { "subtitle": "Pink / L", "price": 120, "compare_at_price": 140, "currency": "USD", "currency_sign": "$", "external_id": "v1", "shop_url": "", "variant": true, "images": [ "", "" ], "option_1_names_path": [ "Color", "Pink" ], "option_2_names_path": [ "Size", "L" ] }, { "subtitle": "Yellow / M", "price": 130, "compare_at_price": 130, "currency": "USD", "currency_sign": "$", "external_id": "v2", "shop_url": "", "variant": true, "images": [ "", "" ], "option_1_names_path": [ "Color", "Yellow" ], "option_2_names_path": [ "Size", "M" ] } ] } } --- language: "en" --- # Katalys Advertiser Integration - WordPress This plugin provides a no-hassle integration for advertisers integrating with the Katalys Performance Affiliate Network. Katalys is a performance-based advertising network for transformational health products and brands. Our publishers deliver high-converting in-market traffic to an exclusive list of curated products on the market. Want more eCommerce customers for your brand? Partner with Katalys to craft an enticing performance offer; we'll do the rest. ## Setup The menu by side clicks in **Katalys Shops Settings** . In the tab of the top, click on the **Network Settings**: ![image-20240606-021544.png](https://kb.katalys.com/__attachments/a_ec5245154b96e4c84021fcd5b1b08d3505a4b6ef9d962f430de4d2ac5c42cf35/image-20240606-021544.png?cb=7d276368095f97acb5f9ccf191be07c3) * **Katalys Site ID** : This is how your website is identified on the Katalys network. The plugin's default will use your website's domain (with any prefix like "[++www++](http://www/)." removed). *Do not change this setting unless directed by a Katalys representative!* * **Use Cron System**: This flag controls whether the plugin uses a stateful background table to track tasks. Using the cron system is suggested as it can improve your website's performance. ## Verifying Installation The plugin adds a snippet of JavaScript to your web pages. This snippet enables Katalys to attribute orders to its affiliates. To verify the plugin has been installed, look at the source code of any public page -- we suggest simply starting with the homepage. The process to view a page's source is slightly different depending on which browser you're using, but most offer an option of "View Page Source" when right-clicking on the page. Within the source of the page, you should see a JavaScript snippet as indicated in this screenshot. ![image-20231215-132518.png](https://kb.katalys.com/__attachments/a_bc7e8277317972586c8ed9431ddc027d826bc0df20a8ad03b0b707945f72ff7c/image-20231215-132518.png?cb=c1e3e4d66fa1d55712135952b656327c) --- language: "en" --- # Katalys Integration No-hassle integration plugin for advertisers with the Katalys Performance Affiliate Network. Katalys' publishers deliver high-converting in-market traffic to an exclusive list of curated products in the market. Want more eCommerce customers for your brand? Partner with Katalys to craft an effective performance offer and Katalys will do the rest! ## Setup You can install the app in just a few steps! 1. **Go to** Click 'Add to Cart' and navigate through the Magento Marketplace checkout process. 2. **Download \& Install the Plugin** The app needs a few basic permissions so that it can add the scripts to your pages. Details on these permissions are below. 3. **The app will register your store** After installing the plugin and clearing your Magento caches, the RevOffers plugin will perform the setup process automatically. After installing the plugin and clearing your Magento caches, the Katalys plugin will execute the setup process automatically. To customize the plugin's operation, you will find two new configuration options. In the Magento Admin Panel, navigate to: **Stores → Configuration →** **Katalys → Advertiser** **Integration** ![image-20240321-121353.png](https://kb.katalys.com/__attachments/a_8232ac660daaf47d9cbcf0edaed92940fa4f07515b2f231d1aa8d068f5891bf0/image-20240321-121353.png?cb=e56318ed378e2573536dd833576fc848) * **Site ID** : This is how your website is identified on the Katalys network. The plugin's default will use your website's domain ( with any prefix, such as "[++www++](http://www/).", removed ). ++***Do not change this setting unless directed by a Katalys representative!***++ * **Use Cron**: This flag controls whether the plugin uses a stateful background table to track tasks. To improve the performance of your site, using the cron system is recommended. ## Verifying Installation The plugin adds a snippet of JavaScript to your web pages. The snippet enables Katalys to attribute orders to its affiliates. To verify that the plugin has been installed and the appropriate Magento caches have been cleared, look at the source code of any public page -- we suggest simply starting with the homepage ( default landing page ). The process to view a page's source code is slightly different depending on which browser you are using, but most web browsers have an option to "View Page Source" when you right-clicking on the page. On the source code page, you should see a JavaScript snippet as shown in below screenshot: ![image-20231215-123531.png](https://kb.katalys.com/__attachments/a_2a5c6c3eb078c633728c2ebf94d1e8a58af61978285751ef30eecc55d290bdd1/image-20231215-123531.png?cb=56e78b0fe908ab5a327182a621fdb252) After validating, please confirm with your Katalys account manager who will coordinate a test transaction with. For support or other inquiries, please contact your Katalys account manager. ## Permissions The app receives "full permissions", as per the Magento Marketplace procedures and guidelines. The scope utilized by Katalys is below: * Adds the Katalys tracking JavaScript to your website. * Sends Order Status updates to Katalys, so to trigger your custom business rules. Your customers are ++**your customers**++! Collected data is only used to attribute that growth where appropriate in accordance with our . Katalys partners with brands to create strong relationships to help you drive performance -- our focus is your success! ## Performance The Katalys plugin registers as few as possible handlers within Magento. To avoid impact to the user experience, the plugin offloads database interaction, or cURL requests, to a background cron-job. This keeps the plugin performant and ensures that multiple updates to orders are handled just once in a batch. The front-end JavaScript component is added via an `async` JavaScript tag. This ensures that our tracking does not block any page rendering. Additionally, all remote requests within our tag occur on a background thread using the `sendBeacon()` API, which prevents the network and CPU requirements from interfering with any rendering threads within the browser. ## Compatibility with other Magento Plugins In general, the RevOffers app is a read-only application. There are no known compatibility issues or concerns with any other applications. An exception here is the "Thank You" page -- Katalys needs to place a conversion pixel to attribute the revenue correctly. If you use an application that modifies or replaces the checkout page, then you must clone the Katalys pixel into that tool's "Conversion Pixel" configuration area. ## Special Considerations ### Multiple Sites Under a Single Offer: If a single offer has multiple sites, all of the Magento installations need to have the same Site ID configured for them. There should ONLY be one (1) siteID, and all of the installations should match. --- language: "en" --- # Katalys Shop Builder - Embedding Instructions Shop builder is an advanced and easy to use editing tool that let's users customize, optimize and tailor Katalys shops to fit any page. Users can customize the way the shops are displayed, sops appearance to fit the page design and/or branding and add parameters to track the performance of shops for individual placements. Once editing and customization is done, users can simply generate an embed code and add it to any clickable asset or embed it into their content. * Katalys shop builder can be launched from Katalys Shops or via URL. * The right tray is the default shop display mode and is pre-opened. ## The Interface * On the left hand side, you'll find various customization tabs: layout, style, tracking, and learn tab. You can switch between those tabs to customize specific properties. Each tab opens a menu with specific property settings. * The center stage is reserved for real-time previewing. * In the top right section of the shop builder page, you can change the layout of the page to preview how shops behave on different devices and screen sizes. * In the top right corner, you'll find a button for sharing the shop builder link and an Embed button to copy and embed code for your creation. ![image-20220908-180624.png](https://kb.katalys.com/__attachments/a_0c3eea459683f4ab823adc82efe2e12f77b05db93b095d11d775f9248d694776/image-20220908-180624.png?cb=0e6d1a9508b14d0fcd7e742bfeb9ea77) ## **Customizing a shop** ### **Layout tab** Choose how you would like your shop to be displayed. #### **Display mode options** The way shops are displayed: * **Right tray:** Displays Katalys shop over the content within the drawer that slides in from the right-hand side. * **Popup:** Displays Katalys shop over the content in a popup lightbox. * **Inline:** Displays Katalys shop as an embedded widget inside the content. ![image-20220908-180700.png](https://kb.katalys.com/__attachments/a_49ef65d8ffe562d6cd5b92c5e985129829a680d6d12d625af2c7e58ba6612a63/image-20220908-180700.png?cb=17d6a4c306767f158ade4d831eab9964) #### **Starting screen options** The starting point of the customer journey. * **Default:** Katalys shop with image gallery, options, details, etc. * **Cover:** Displays cover image first. Best for ads. By default, the hero image of a product is selected as a cover image. Alternatively, any image can be uploaded as a cover image. The uploaded image will be resized and positioned automatically. * **Payment methods:** Directs users directly to the checkout screen. * **Collection:** Displays all products in the shop first. ![image-20220908-180730.png](https://kb.katalys.com/__attachments/a_0e11528b0c9a4bce2663e188234c8cebe516be464879a003563bf032cf660e0f/image-20220908-180730.png?cb=94d02e293b1c5a5a807d16c884e1eefe) #### **Inline display mode layout options** Inline display mode lets you embed the shop within the content, just like YouTube videos. If this display mode is selected more layout options are available, like responsive mode and various fixed modes for ads and videos. ![image-20220908-180823.png](https://kb.katalys.com/__attachments/a_d7c0f6e3e63b1443b5e987bd09afa1dc834338bf40a7d6d3a5df2a60bf9d4848/image-20220908-180823.png?cb=a7d4f5c93b87e3dea807647c67cd3d5c) ### **Style tab** Customize shop appearance to fit the page design or branding. ![image-20220908-180847.png](https://kb.katalys.com/__attachments/a_6080abdb0a8724e53d72bdf862756133c3ddc96bb8c11126515795accc24602e/image-20220908-180847.png?cb=d6b0e611b7b15c17bc6b9bc8b3f5b53e) Set the button color, text color, button CTA, and background color or simply disable the background and make the content scrollable beneath the shop (useful for content-heavy articles). If an Inline display mode is selected, additional parameters are displayed like border, drop shadow, etc. ### **Tracking tab** Add parameters to track the performance of your shops for each individual placement. ![image-20220908-180938.png](https://kb.katalys.com/__attachments/a_9a49b56e8e74dbe1056d8f460fea476238790e6d9ffc03ba1706d8720eaa1389/image-20220908-180938.png?cb=8dc0595c797392d48ec2158523b7fb3d) Add slug, placement ID and UTM parameters. * **Shop slug:** Shop slug is appended to your shop URL and enables you to differentiate between different placements of the same shop to compare each of the placements performance individually. We strongly recommend you use slugs for each shop you create or customize. * **Placement ID:** Placement ID enables you to differentiate between different placements of the same shop to compare each of the placements performance individually. * UTM parameters: * **Source**: Social network, search engine, newsletter name, or other specific source driving the traffic e.g. utm_source=google * **Medium**: The type of channel driving the traffic: organic social, paid social, email, etc. E.g. utm_medium=paid_social * **Campaign**: A campaign name could be the product name, a code to identify a specific sale or promotion etc. E.g. utm_campaign=sale ## **Sharing Shop builder link** Share shop's preferences and parameters with others or copy and save it to return to it and edit shops later. ![image-20220908-181039.png](https://kb.katalys.com/__attachments/a_ea21a7183d215a6a5b90f3845d68dbb0655fa1ad1d9b263e76582aae1bde7510/image-20220908-181039.png?cb=76ade495532af7c51683401962ae4580) ## **Embedding Katalys shops** Get the embed code by clicking the Embed button in the top right corner of the page. This opens a drawer with the embed code and all the instructions on how to embed this shop. NOTE: Switching between different modes and setting parameters in tabs while the embed drawer is open will update the instructions and the code in real time. Right tray and popup display modes require a Katalys.js tag placed in the header of the page, where it will be displayed. 1. Make sure Katalys.js script is included on your page If Katalys.js is not yet included, users can expand the instructions by clicking Show more link and get the Katalys.js tag with instructions: Place the Katalys.js tag below between the \ and \ tags of your website HTML. ![image-20220908-181150.png](https://kb.katalys.com/__attachments/a_18d4daf30ea4e49ea805ebdd2cd3be1d753983046eea9c80af9e214f009df7eb/image-20220908-181150.png?cb=e819374b7c4a0e79f2b9feafa4ba85ad) ![image-20220908-181202.png](https://kb.katalys.com/__attachments/a_e5bc4f3ce6e9dc6d21296de15904ca29740054b442b499b2a94066da8787a454/image-20220908-181202.png?cb=88acb1182265d2fb2f81be034fcc7b1a) NOTE. Embedded inline Katalys shops don't require Katalys.js. Katalys shops will be displayed within the content like YouTube videos. ![image-20220908-181227.png](https://kb.katalys.com/__attachments/a_9bc09dec822df2ac43f6355510c0410a9102949cfdf67be72915025b61ea6d23/image-20220908-181227.png?cb=3823d0218211d1da6f2c7a719f11d014) 2. Copy and place the Katalys shop link Copy and insert the link below to any clickable asset like text, image, button or video in your preferred editor to open Katalys shop in the right tray. ![image-20220908-181305.png](https://kb.katalys.com/__attachments/a_e0270cf062667e6c13e3557ea78732e5dc5ebfe569e556a6ba08738da151bcb2/image-20220908-181305.png?cb=137426eba32ab74573ae6e574f78c202) 3. Use the Katalys Debugging Tool Visit [++**Katalys.js checker**++](https://1o.io/checker) to check and validate if you have successfully embedded the Katalys shop link and Katalys.js script. ![image-20220908-181355.png](https://kb.katalys.com/__attachments/a_a649d18c43927b3b83274f2486d02333ab5b1ec7f8ae1b8dcab7612c3646df78/image-20220908-181355.png?cb=352ab42ec068780181825e85c4e39519) **How to: Examples \& use cases** Further instructions on how the embed code can be applied to various clickable assets. ![image-20220908-181421.png](https://kb.katalys.com/__attachments/a_177a5bb0c07538fb12a8c1b044b633e14a336e37ac4a3eb3a9600eb23e971375/image-20220908-181421.png?cb=fcfd6a8b0739e88817bf09c4cc718ef4) --- language: "en" --- # Katalys Shop Configuration Open the Admin interface and go to Stores -\> Configuration: ![image-20240321-121628.png](https://kb.katalys.com/__attachments/a_db12a153de66a785a185746535bc1520d6260977e3a49063021f7fc58bd32b4f/image-20240321-121628.png?cb=841e407ff1717857cc3d1abd363e0c28) ![image-20240119-141602.png](https://kb.katalys.com/__attachments/a_fee10067bf3ec78ed2d1f45e6695cf983999acdc033be4aa242834838a830f13/image-20240119-141602.png?cb=00c24ceba959c95fd6877f58001448b7) The configuration above will be found in your Katalys account. * Access the link and login with your account. * When you access the platform with your username and password, you will be redirected to profile. * Click on the button below and after that on the shop: ![image-20240119-133554.png](https://kb.katalys.com/__attachments/a_d9bc0935c085ead7bdc8911588d4812c48b6680979dee26f71407fa9dfc6a8b9/image-20240119-133554.png?cb=c0ca468c0cea6b355ad9ed6ecb49825e) * Click on the Store menu: ![image-20240119-133749.png](https://kb.katalys.com/__attachments/a_c71ba33bbf14c9880297e94ab5f199d1e5a01f3340ed4de41be3c1c6d839af91/image-20240119-133749.png?cb=64a30f423fe26d053f2e8760cdc31d64) * Access your store, click on the Install tab and follow the instructions. * After that, clear the cache and you are all set. --- language: "en" --- # Katalys Shop Configuration - WordPress ## Step 1 After installing the plugin, look for **Katalys Shops Settings** near the bottom of the side navigation menu: ![image-20240119-141336.png](https://kb.katalys.com/__attachments/a_339bb0bb7503c4d0ad88afe64496c644b9299bcdc815be38fd7403237531022f/image-20240119-141336.png?cb=c79c372b4b7ea22777be6d3e352dcca4) ## Step 2 The configuration above will be found in your Katalys account. 1. Access the link to log into your account. When you access the platform, you will be redirected to your Profile. 2. Click on the App Switcher to select the appropriate platform, as necessary: |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ![image-20240123-233942.png](https://kb.katalys.com/__attachments/a_2ce34785992f1a2da8e29f78b4d365916d73c31b5e6a02c5c3ca7d29441ca237/image-20240123-233942.png?cb=983b6cd7e0709bc31296187166ec0509) | ![image-20240123-233756.png](https://kb.katalys.com/__attachments/a_a8373562f7c8f6a2eef012ec66d3bb648749c93846209ee2b7b6a6d990182b6d/image-20240123-233756.png?cb=25e14bc765a8a301508097c8712b4efd) | 3. Click on the button below and after that on the shop: 4. ![image-20240119-133554.png](https://kb.katalys.com/__attachments/a_773c6441f3aeea991c96bd5793e514bd2580926f23edd5aefd1563afe5d8614b/image-20240119-133554.png?cb=c0ca468c0cea6b355ad9ed6ecb49825e) 5. Click on the Store menu: ![image-20240119-133749.png](https://kb.katalys.com/__attachments/a_0cca059999a3798c3bc86f1e48873dedd4b3cefdc04a457c9067a7259c8497ef/image-20240119-133749.png?cb=64a30f423fe26d053f2e8760cdc31d64) 6. Access your store click on the Install tab and follow the instructions. --- language: "en" --- # Magento: Coupon discount for free shipping You can add a coupon to give free shipping for the Katalys platform. This coupon won't be available to use in your store. This coupon won't be able to give a discount, will give only free shipping. ## **How can You add the coupon?** The menu by side click in **Marketing → Promotions → Cart Price Rules.** ![image-20231215-120255.png](https://kb.katalys.com/__attachments/a_71486b28286d687bebf71645c9f0555c50155c289c8b7a9fd2e5b13fcbbd84cf/image-20231215-120255.png?cb=ba3d681192be0013ba319dc5776da8df) Click on the Add New Rules: ![image-20231215-120414.png](https://kb.katalys.com/__attachments/a_31042b969d391b81371d7f8813685059f0cc94b63ecd14e6ceaf24e986f17a38/image-20231215-120414.png?cb=fc26454c162fac8b21a31fea2017bdac) After that, you need to put a Coupon code. The coupon code needs to start with the prefix **KS_** to work and select the field **Free Shipping** option **For matching items only.**We have an example below: ![image-20231215-120943.png](https://kb.katalys.com/__attachments/a_0f46db7cb4dc15489a97a81e5b2c3e44b594f8e079889c215a76d434595e84a8/image-20231215-120943.png?cb=4daef1ee925c21f3fe38c302fd241fc6) ![image-20231215-121600.png](https://kb.katalys.com/__attachments/a_e28548b87d8758f10dc6cdc534813e2274f49244ecd96537383602a6f46cf947/image-20231215-121600.png?cb=86322bcc58ce2df35b2a993a0e2bae8a) ![image-20231215-121017.png](https://kb.katalys.com/__attachments/a_4011a0f92bf6121201fef010ff4dd950ecd15fa4f76fb8d940dab587ac8892f5/image-20231215-121017.png?cb=e34b396592393d836b5af00c2bc1dc07) ![image-20231215-121031.png](https://kb.katalys.com/__attachments/a_c71b6503611b40cc29a3da2cdf13f80731af328f8ef4e68ee251f54ec70c037f/image-20231215-121031.png?cb=5eadffdbf60108ec86e9bc7991a3e7a5) You need to create the coupon with the basic information above, or else won't work correctly because the Magento won't apply. After you create a coupon, will be available automatically to use via the platform. The platform will show only free shipping if you create the coupon, and won't show others shipping rates, the example below: ![image-20231215-121846.png](https://kb.katalys.com/__attachments/a_bf85481b15c6ad7cbce25897a8bb5ed7a0182c738eccabdc19fb68d787f0f225/image-20231215-121846.png?cb=65522f77c2710f194a6b29d5efd095d2) After you add the coupon, when you have an order with the coupon, you will see the order equal below: ![image-20231215-121946.png](https://kb.katalys.com/__attachments/a_b6db693fdbfb39ef91b007e127de3cb892382178370c850b6eabeb38949c31ae/image-20231215-121946.png?cb=b04f533066601a04e353dc3de75b433b) If you try to use the coupon in front of the store, You won't be able to use, the example below: ![image-20231215-122137.png](https://kb.katalys.com/__attachments/a_7d8abb1f2869f6a513ff8d1e4ba99df622ad1b74d0c438461b8a766889f6cfff/image-20231215-122137.png?cb=0bdf45772d15edb082f1d12bf32b4293) --- language: "en" --- # Magento Plugin ## Topics [Magento Module Installation ( first-time installation )](https://kb.katalys.com/shop/module-installation.md) [Katalys Integration \[Magento\]](https://kb.katalys.com/shop/katalys-advertiser-integration-magento.md) [Free-Shipping Coupon \[Magento\]](https://kb.katalys.com/shop/coupon-discount-for-free-shipping-1.md) [Katalys Shop Configuration \[Magento\]](https://kb.katalys.com/shop/katalys-shop-configuration-magento.md) --- language: "en" --- # For Merchants This documentation focuses on the interaction between **Katalys** and a **merchant**. In order to work with the Katalys technology, a Merchant must have a connection that is capable of receiving orders placed by online customers. This Bridge component can be fulfilled by an Approved Plugin or by building your own. *** ** * ** *** ## Install Approved Plugin View our list of approved plugins to jump-start your integration. [**Get Started ⇢**](https://kb.katalys.com/shop/merchant-plugins.md) preferred *** ** * ** *** ## Build Custom Integration You can build your own integration to be compatible with your custom CRM. [**Learn More ⇢**](https://kb.katalys.com/shop/building-a-custom-integration.md) *** ** * ** *** ### Goals of Katalys custom integration 1. Products selling on merchant's store can be automatically turned into Katalys Shops. 2. Purchases made with Katalys Shops are automatically inserted into the merchant's store as if the purchase happened in the store itself. Choose an integration option above to get started. --- language: "en" --- # Merchant Plugins This section contains documentation for our approved plugins. Choose a page below for more information about that plugin. * [Shopify App](https://kb.katalys.com/shop/shopify-app.md) * [WordPress/WooCommerce Plugin](https://kb.katalys.com/shop/wordpress-woocommerce-plugin.md) * [Magento Plugin](https://kb.katalys.com/shop/magento-plugin.md) --- language: "en" --- # Magento Installation Magento module for Katalys integration. This is required only when doing the first installation. ## Installation ### Step 1 Run the following command to install the package using **Composer**: Bash composer require katalys/magento-bridge-module ![image-20240320-133532.png](https://kb.katalys.com/__attachments/a_3eade4e50213077e704101eabadf13b6f750ca422752b8fe6e29d361d37ff33b/image-20240320-133532.png?cb=f45e342d3af1fd822b03af61eb17c9d7) If the installation requests the token, click on the link and GitHub will create the token for you; else, continue with the installation process. ### Step 2 Enable your module: Bash bin/magento module:enable Katalys_Shop ![image-20240320-133806.png](https://kb.katalys.com/__attachments/a_aa0441f41cd7649f71f7b839cf6b31284d21bb30f11a01cd67fe886cde40dc9e/image-20240320-133806.png?cb=b23c74778366acff23c5bc4615900a3e) ### Step 3 Execute the command below: Bash bin/magento setup:upgrade ![image-20240320-133837.png](https://kb.katalys.com/__attachments/a_753c3f3630fec65958736344b3b1a38ccbecefce5ce7b3292080c02002802e9b/image-20240320-133837.png?cb=55fc53b7dd58a54dea924d9ad1053f07) ### Step 4 Execute the command below to compile the Magento: Bash bin/magento setup:di:compile ![image-20240320-134218.png](https://kb.katalys.com/__attachments/a_4480040bb3bdb41727cbac2e9100ef9d59d17b5e200d5fd7676e1a3b577ae699/image-20240320-134218.png?cb=be10664dca96175a97e228cfa5ec1a71) ### Step 5 Execute the command below to compile the theme of the Magento: Bash bin/magento setup:static-content:deploy ![image-20240320-134336.png](https://kb.katalys.com/__attachments/a_5dd499129c395ddf77cbba6cd41d07b2490f5b601fb43593a602cc6026a7e0c9/image-20240320-134336.png?cb=b3e7cb911941c19521d4c10ca0af8830) ## How to Update To update this module, run the following command: composer update katalys/magento-bridge-module Note that this will also update any other packages in the project according to composer definition. Depending on the nature of the update, the following commands may also be required: bin/magento setup:upgrade bin/magento setup:di:compile bin/magento setup:static-content:deploy ## Version Rollback If you experience an error with the newly installed plugin, you can revert to the last version. If you install version 1.0.1 and need to rollback to the last version that worked 1.0.0, reference the example below: composer require katalys/magento-bridge-module:1.0.0 bin/magento setup:upgrade bin/magento setup:static-content:deploy bin/magento setup:di:compile If after rolling back to the prior version you experience an error, please send an email describing the issue. In the email, please provide the below information: * Magento version * Module Version * PHP version * Description the error * Step-by-step instructions that led to the error * Screenshots ( and on-screen recording, if possible ) Send the email to [techsupport@katalys.com](mailto:techsupport@katalys.com) ## Removal Run the following command to remove the package using **composer**: php bin/magento module:disable Katalys_Shop composer remove katalys/magento-bridge-module php bin/magento setup:static-content:deploy php bin/magento setup:di:compile --- language: "en" --- # Order Processing ## About Simply put an Order is a collection of line items. A line item is a product times quantity. Order processing revolves around figuring available shipping options for the set of line items, pricing and taxes, availability and once the shipping has been chosen and payment made inserting the order into the merchant's store. ### Price discrepancies It might occur that the product on Katalys's side was priced differently than the same product in the merchant's store. This is usually due to legal agreements between Katalys and the merchant. To account for possible differences the integration should ensure line items prices of the inserted order match those coming from Katalys GraphQL API `order.lineItems.price`. This can usually be achieved by changing line items on the inserted order. Options vary between the price or applying discounts on individual line items. ## Firing order related directives from the UI Preconditions 1. You successfully imported a product - [Importing Products](https://kb.katalys.com/shop/importing-products.md) Setup a test payment gateway to accept a test credit card 1. Click Settings - left menu, bottom 2. Click Payments \& Payouts 3. Click Manual Integration 4. Input Live API Keys 1. Reach out to Katalys to get them Steps 1. Create a shop 1. visit Products - left menu 2. Chose a product in the list, click three dots - right side of the row 3. Click create Shop 2. Preview the shop 1. visit Shops - left menu 2. click on a shop 3. click "Preview" - top right 3. Performing a purchase 1. Click on BuyNow and follow through till the end 1. Test card - repeat "42" until all fields are filled. This will results in: `4242 4242 4242 4242` `04/24` `242` 2. Expect an order to in the Orders list - left menu 3. Expect directives being fired and recorded in the Store's Log tab 1. Settings, Stores, Store, Log ## Servicing the `update_available_shipping_rates` directive When an order on Katalys is created or updated, Katalys might issue this directive to your integration. JSON { "directives": [ { "args": { "order_id": "91997424-0c62-4525-8043-f00de23cb91c" }, "directive": "update_available_shipping_rates", "id": "45a42385-8ebd-45bb-9ac8-c7365aa157ac" } ] } Once your integration has calculated shipping rates for the given order, it should use a mutation to update the order with this new information: GraphQL mutation UpdateShippingRatesExample($id: ID!, $input: OrderInput!) { updateOrder(id: $id, input: $input) { id shippingRates { handle amount title } } } JSON { "id": "235c9162-80c2-4fd4-9eb8-e398ed130329", "input": { "shippingRates": [ { "handle": "economy-international-4.50", "title": "Economy International", "amount": 450 }, { "handle": "express-international-15.0", "title": "Express International", "amount": 1500 } ] } } Each shipping rate is specified with the following fields: * `handle` is internal to you, the integrator. In the above example, the format is borrowed from Shopify and includes the amount (which makes it work like a cache key, smart!) * `title` is the title that Katalys will display to the buyer during the checkout process (among other places) * `amount` is the decimal amount represented in cents (as an integer). You should assume that the currency here is the same as the one used on the order (but let's talk about this soon to see if the assumption is sane). When shipping rates for an order can't be calculated, Katalys expects the integration to set the `shippingRatesError` field instead. For example, let's consider the case where an order can't be shipped to a given country: JSON { "id": "235c9162-80c2-4fd4-9eb8-e398ed130329", "input": { "shippingRatesError": { "code": "no_shipping_rates", "userMessage": "Unfortunately, we're unable to ship to your address.", "details": "(This is optional.)" } } } `"no_shipping_rates"` is the only recognized error code at the moment of writing. However, your integration is free to set custom error codes for other purposes. ## Servicing the `update_tax_amounts` directive JSON { "directives": [ { "args": { "order_id": "91997424-0c62-4525-8043-f00de23cb91c" }, "directive": "update_tax_amounts", "id": "6e1efe64-2f37-40c4-8198-c8b7827dba5d" } ] } As the name suggests, this directive expects your integration to update tax amounts for a given order, according to the amounts calculated by the Merchant's e-commerce platform. There are two fields to update: * **Mandatory** : the `totalTax` field on Order should contain the total tax amount for the order, calculated based on the **line items** and the `totalShipping` amount (where applicable). This field is mandatory because it precludes the calculation of the order grand total. If the tax amount is zero (e.g. due to tax exemption) a value of `0` must be specified. A value of `null` signals that the tax still hasn't been calculated, in which case the integration must indicate a failure in the response (see [Forming a response](https://www.notion.so/Order-processing-263e0e53792b4e4384a4e70f1d6ba1d1) below). * Optional: the `tax` field on each LineItem should contain the tax amount for that specific line item. This field is for evidence only and does not directly affect the total tax amount on the order (`totalTax` should to be independently set as described in the previous step) GraphQL mutation UpdateTaxAmountsExample($id: ID!, $input: OrderInput!) { updateOrder(id: $id, input: $input) { totalTax lineItems { tax } } } JSON { "id": "235c9162-80c2-4fd4-9eb8-e398ed130329", "input": { "totalTax": 250, "lineItems": [ { "id": "4af7128c-7f22-4efb-9f85-25bbc23d82e2", "tax": 150 } ] } } 💰 `totalTax` and `tax`, like other money amounts, must be represented in cents. For example, the amount 12.99 is represented as the integer value `1299`. 🧾 `usProductTaxCode` - For products that are either exempt from sales tax in some US jurisdictions or are taxed at reduced rates, a Product might have a tax code stored in the `usProductTaxCode` field. The codes are specified by TaxJar. The product can be accessed through a LineItem, using `product` and `variant` fields. ## Servicing the `update_availability` directive JSON { "directives": [ { "args": { "order_id": "91997424-0c62-4525-8043-f00de23cb91c" }, "directive": "update_availability", "id": "ee4d346f-de86-4285-934c-a9f1b9c5c0ed" } ] } During checkout, there comes a time when the system must check inventory levels to determine if enough items are in stock to satisfy the order. Katalys will issue this directive to the integration, which in turn should update each line item to signal its availability (or lack thereof). The checkout process will only be allowed to continue if **all line items are available**. GraphQL mutation UpdateAvailabilityExample($id: ID!, $input: OrderInput!) { updateOrder(id: $id, input: $input) { id lineItems { id available } } } JSON { "id": "235c9162-80c2-4fd4-9eb8-e398ed130329", "input": { "lineItems": [ { "id": "711d0515-0dca-445d-b2a2-1478547763f9", "available": false }, { "id": "fe46588f-57ea-4b5b-9970-25687b59286b", "available": false } ] } } 💼 An integration should consult the merchant's inventory levels. It should also check whether a product is allowed to still be sold when stock reaches zero (in which case the line item should be marked as available). ## Servicing the `complete_order` directive This directive is sent when an Katalys order's `paymentStatus` changes to `paid`. To service this directive the integration must update the Katalys order's `fulfilmentStatus` to `"FULFILLED"` and set the `externalId` value to the order id used by the eCommerce stack. Example: `gid://shopify/Order/5113822838965` - Shopify order id GraphQL mutation CompleteOrder($id: ID!, $input: OrderInput!) { updateOrder(id: $id, input: $input) { id fulfillmentStatus } } JSON { "id": "235c9162-80c2-4fd4-9eb8-e398ed130329", "input": { "fulfillmentStatus": "FULFILLED" "externalId": "gid://shopify/Order/5113822838965" } } This is the time when your integration should *insert an order into the Merchant's store*. 🧠 Note that Katalys could issue this directive more than once for the same order, so it must be serviced in an *idempotent* way -- i.e., running it multiple times with the same order ID only results in a single order in the Merchant's store. Your integration might want to store additional metadata on the order through the Katalys GraphQL API. [Read more about the](https://kb.katalys.com/shop/external-ids.md)`externalData` field. ## Forming a response Once your integration is done servicing the directives and updating the order, it should form a response to the initial POST request that issued the directives. The response should have a 200 status if everything went OK and the directives could be successfully performed. In every other case the response should be non-200. We can decide on the format of the response, but for now this we recommend this (a list of objects, one for each received directive): --- language: "en" --- # Overview ## What is Katalys? **Katalys** provides embeddable **Katalys Shops** that allow anyone on the internet to purchase a product at the exact place where it was first seen. Katalys does not sell its own products---we sell products from other companies we call **merchants**. To see some examples checkout our demos. *** ** * ** *** ## [See our Demos ⇢](https://demo.1o.io/) *** ** * ** *** ### [For Publishers](https://kb.katalys.com/shop/publisher-tools.md) Learn how to implement the Katalys Shop on your publishing property or website. ### [For Merchants](https://kb.katalys.com/shop/merchant-integration.md) Learn more about how to integrate with 1o as a merchant that sells products. --- language: "en" --- # Plugin Installation ## Installation You can find the plugin in the link below or by searching for **Katalys Merchant Sales Bridge**: ![image-20240119-140307.png](https://kb.katalys.com/__attachments/a_59380c5266644ede75bd120f87d2ba71ca2487fedaccb6b7d23e46bf1533a997/image-20240119-140307.png?cb=3ac65fec7651bf3d3e1faa6d1acdb9c3) ## Update ### Automatic Updates If your plugin or theme is listed in the [WordPress.org](http://wordpress.org/) repository, these plugins and themes will automatically update. Your site will check for new versions regularly and automatically install the latest version for you. If you're unsure if a plugin is in the [WordPress.org](http://wordpress.org/) repository, [search for it here.](https://wordpress.org/plugins/) If you installed a plugin by going to *Plugins → Add New* in your [WordPress.com](http://wordpress.com/) dashboard and using the search function to find it, those plugins are from the [WordPress.org](http://wordpress.org/) repository. #### Disable Automatic Updates Although we do not recommend turning off automatic plugin updates, you can do so by following these steps: 1. Visit your site's dashboard. 2. Navigate to *Plugins → Installed Plugins*. 3. To the right of each plugin, there will be a column for "**Automatic Updates**". 4. Click the link "Disable auto-updates" to turn off automatic updates for the plugin. * If the link says "Enable auto-updates", that means automatic updates are already switched off. * Some plugins will say "Managed by host", meaning we keep this plugin safely up to date for you. ![image-20240321-122757.png](https://kb.katalys.com/__attachments/a_9708f7e33f5cf9b7894612f4baa1eab34e9f8c28504995cfe2daf8ae80eb1846/image-20240321-122757.png?cb=d8d39393ce915b7a2cb7254127d812c6) You can install old or out-of-date versions of plugins or themes if needed for compatibility issues, but you would also need to disable automatic updates to remain on the older version. #### Check for Plugin Updates To check if there is a new update for one of your installed plugins: 1. Visit your site's dashboard. 2. Navigate to *Plugins → Installed Plugins*. 3. If a plugin has an update available, you'll have a notice and a link that says "**Update now**": A plugin with an update available ![image-20240321-122959.png](https://kb.katalys.com/__attachments/a_8a151d7c7305dccecb1c6b7593f107bfde764738d7997bcfb5df140d658fccb5/image-20240321-122959.png?cb=8a1b073447d5e1100d0198da70bf0c77) If you have a lot of plugins installed, you can use the filter at the top of the screen to show only plugins with **updates available**: ![image-20240321-123048.png](https://kb.katalys.com/__attachments/a_c0d230f04e6e2e3ab9f2825d0a55382e67689b00bdf5f26230a576b32d9ec8cc/image-20240321-123048.png?cb=dc762ff797b16c684452cedf85b6b5d8) --- language: "en" --- # Product information sync ## Triggering `product_information_sync` Product information sync directive is fired on a schedule every 1 hour. It requests information for products specified in the directive request body. ## Expected data from sync We're expecting a subset of information on the product, which is going to extend in the future. Here are the attributes that are expected with log of changes below. { price: Int, compare_at_price: Int } * 1.0 - Initial batch ## Servicing the directive `product_information_sync` directive comes with data. It provides Katalys product id and the `external_id` associated with the id. This is the identifier from the integration. Format of the request data: JSON { "directives": [ { "args": { "product_ids": [ { "id": product_id, "external_id": external_product_id "variants": [ { "id": variant_id, "external_id": external_variant_id } ] } ] }, "directive": "product_information_sync" } ] } Use `external_id` to identify the correct product on the store and attach data needed for the sync. It is specified in the section above. Minimal response must include expected data and Katalys id inside the attribute `id`. Format of the response data: { "results": [ { "data": [ { "id": "katalys_product_id", "variants": [ { "id": "katalys_variant_id", "compare_at_price": Int, "currency": "currency", "price": Int }, { "id": "katalys_variant_id", "compare_at_price": Int, "currency": "currency", "price": Int }, ] }, { "id": "katalys_product_id", "variants": [ { "id": "katalys_variant_id", "compare_at_price": Int, "currency": "currency", "price": Int }, ] } ], "source_directive": "product_information_sync", "source_id": "directive_id", "status": "ok" } ] } ### Note 1. There can be multiple Katalys Products with the same external_id. That's why Katalys ID is required in the response. 2. A Katalys Product has an ID that is unique in the Katalys' database 3. A Katalys Product has an external_id that is unique in the Merchant's database --- language: "en" --- # For Publishers Here is docs from pub api docs. Please copy content from: ## [See our Demos ⇢](https://demo.1o.io/) --- language: "en" --- # Salesforce: Shipping Promotions All types of Shipping method promotions can be set up and used in Katalys Plugin but the following steps should be taken to make sure that promotions are set properly. 1. Set up a promotion at **Merchant Tools \> Online Marketing \> Promotions** 2. Make sure to select **shipping class.** ![shipping class.png](https://kb.katalys.com/__attachments/a_27f214927d81a207900ea0e6a585bce299154ba21fea5ac16c57b3cbe3880640/shipping%20class.png?cb=04d4097c62a9ef2207e8c8ac090a58fc) 3. After setting up the shipping class make sure to assign a campaign to the promotions. ![shipping campaign.png](https://kb.katalys.com/__attachments/a_997040a480a2c342f5391f5c760b254db37f14dcb66ce568835908fbe7882a89/shipping%20campaign.png?cb=102a2c966c27682a0a174a4243b9058b) 4. Navigate to **Merchant Tools \> Site Preferences \> Custom Site Preference Groups \> Katalys** **\>** **Katalys Free Shipping Methods,** and fill in the ids of shipping methods you want the promotion to affect separated by a comma. ![customshipping.png](https://kb.katalys.com/__attachments/a_6a7392ea8f860a10e5ab1db70270c2d2e3dfe008f2d46a29788dc636030cf0d8/customshipping.png?cb=dba1c3ab7a91d2c55b69436ec9049d69) ## Result ![image-20231206-100513.png](https://kb.katalys.com/__attachments/a_b80ba357d289f6a6f5594123d605e0545c3d3c70f39774b8fc8ca937cb52cd8d/image-20231206-100513.png?cb=e4253d611f8b272a66dc9690d2a81ec4) All shipping methods qualified for the Free Shipping promotion ![image-20231206-100557.png](https://kb.katalys.com/__attachments/a_5b231f248ca94b630e87c8d8d140cd7562eef928fc55b1a4e2961d0de4305cca/image-20231206-100557.png?cb=de3599969fb7bedbee48e455a9c5383f) Part of the shipping methods qualified for the Free Shipping promotion --- language: "en" --- # Shopify App Documentation coming soon --- language: "en" --- # Technical Documentation This documentation explains how to include an existing Katalys Shop into your content. What is a Katalys Shop? [Click here](https://1o.io/checkouts/966e7ba9-e36b-4733-ba86-732f30c40018) or visit our [demo site](https://demo.1o.io/) to explore use cases.How can Katalys Shops benefit your business? Read more [about Katalys](https://www.katalys.com/). How can you set-up your own Shop? [Reach out](https://calendly.com/tormn/30min?month=2021-01) and we'll help you! We are friendly. ## Topics: * [Shop URL](https://kb.revoffers.com/shop/shop-url) * [1o.js Script](https://kb.revoffers.com/shop/1o-js-script) * [URL Options](https://kb.revoffers.com/shop/url-options) * * [Step-By-Step How to Embed and Validate a Shop](https://kb.revoffers.com/shop/how-to-embed-1o-shops) --- language: "en" --- # Setup Test Environment ## The goal Integrator gets access to a sandbox to develop test and break things freely. It also allows crating fully functional shops that sell products imported via the integration. These shops then create orders are sent to the integration at various stages. Most importantly it provides tools to inspect every message between Katalys and the integration and also a way to retry these messages thus providing a real time feedback loop when developing the integration. ## Setup a Katalys sandbox account 1. Create an account on Katalys sandbox environment 1. [https://auth.dev.katalys.com](https://auth.dev.katalys.com/signup) 2. Click on Sign-Up 3. Complete the signup (Note: Signup with Google is reserved for Katalys mails) 2. Navigate to Katalys Shops 1. Click on the Open button in the Katalys Shop banner 3. Create an organization 1. After the organization is created we suggest bookmarking the current page 4. Navigate to: Settings → Apps and Integrations → Stores 1. Click add Store 2. Click Custom integration 1. Side note 1. Here you can inspect how the user experience flow for existing integrations, part of rolling out a new integration is also about writing instructions for merchants to set it up 3. Fill in the form 1. **Notice:** endpoint for accepting Katalys directives 1. This has to point to a server running your code 2. It's OK to put in something temporary, can be changed later 3. In case your plugin will run on your local development machine, we suggest using a service like that can make your local server accessible from the outside world 4. Click create integration. 1. You might see an error message. This is expected if the endpoint is not running. 5. Inspect integration's tabs 1. API keys 1. crucial information to talk to our GraphQL API 2. Logs 1. every message sent to your endpoint and received from your code will log here. So you can easily debug request and response payloads. 3. Settings 1. Here you change the URL location of your plugin and other basic info 6. Click on Logs tab 1. There you'll see a **Health check** button, by clicking it a request with authentication headers will be sent to the url you specified while setting up the Integration 2. If the url is reachable and responding, you'll see a request and response appear in the log 3. **Notice:** This way you trigger a request any time you need it and inspect the result. This tool is intended to help you develop and debug the connection. 7. Done. You now have an environment in which you can manually fire a request to a URL of your choosing. Next step is to setup a server that will receive the request, authenticate it and reply properly. ## Integration's source code 1. Work with Katalys to setup a Git repository 2. Setup a project that will start a server and expose a URL endpoint 1. Example: [http://some-development.server.net/katalys/directives_endpoint](http://localhost:9000/katalys/directives_endpoint) 2. In case you want to run the development server from localhost, you can use a tool like to make it publicly accessible 3. Put that URL into your sandbox (see above) 4. That URL endpoint will receive post messages 1. containing authentication headers 2. containing JSON payload in body 5. Ensure authentication headers are properly verified - [Authentication](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1638006806) 6. Parse the JSON payload which contains an array of objects called [directives](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1637613663) 7. Process each [directive](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1637613663) individually and store it's result and return a JSON object. ## Next steps: Authentication [Authentication](https://revoffers.atlassian.net/wiki/spaces/KMA/pages/1638006806) --- language: "en" --- # WooCommerce: Enabling Free Shipping "Override" within K-Shops You can add a coupon to give free shipping for the Katalys platform. This coupon won't be available to use in your store. This coupon won't be able to give a discount, will give only free shipping. ## **How can You add the coupon?** The menu by side click in **Marketing -\> Coupons**: ![image-20231201-021924.png](https://kb.katalys.com/__attachments/a_36494eaeb1afb7daff40e3090f4a4a598a7b90f164152fdcad73e7eae2cfd330/image-20231201-021924.png?cb=032b8aec2a8836d6d4c180ddf63ac6cd) Click on the Add coupon: ![image-20231201-022001.png](https://kb.katalys.com/__attachments/a_28fa4cfd0786e9d323c1a8ce478926a41d45d50cf3fc398eb99dfde60dbeeb01/image-20231201-022001.png?cb=3a5464e02c16507579a5e11cb611865c) After that, you need to put a Coupon code. The coupon code needs to start with the prefix **KS_** to work and select **Allow free shipping**: ![image-20231201-022108.png](https://kb.katalys.com/__attachments/a_ed0e051d97ffe4a311c9893d2c30519b165befb22f8442a648bce4249ba4f535/image-20231201-022108.png?cb=fc32c8c320ee481fb626b050677e17b9) If you don't put the prefix KS_ and select **Allow free shipping**, won't work correctly. If you try to use the coupon in your store, will happen the error below: ![image-20231201-022138.png](https://kb.katalys.com/__attachments/a_3ca6a0a284c1cde4a6f5db298bd997d93b412a1e59f69d7f1542f2eb5740c4e1/image-20231201-022138.png?cb=2353c8a8c7254d96c004da69a73a146e) After you create a coupon, will be available automatically to use via the platform. The platform will show only free shipping if you create the coupon, and won't show others shipping rates. After you add the coupon, when you have an order with the coupon, you will see the order equal below: ![image-20231201-022212.png](https://kb.katalys.com/__attachments/a_39f7830609161e5a07cd75b314b3dbaafc8acc09ffa8fd23c59a5a92ab5a5495/image-20231201-022212.png?cb=26b0d2da39711d239abd11cc047db662) The feature above is available in version **1.1.15** or more. --- language: "en" --- # WordPress/WooCommerce Plugin Documentation coming soon --- language: "en" --- # Katalys Marketing Knowledge Base ## Katalys Marketing Knowledge Base The Katalys Performance Affiliate Network drives performance marketing across many verticals. Here you can find technical documentation, descriptions of our pro... [Learn More](https://kb.katalys.com/kb/why-revoffers.md) ### Choose a Section #### [For Advertisers](https://kb.katalys.com/kb/for-advertisers.md) #### [For Partners](https://kb.katalys.com/kb/for-affiliates.md) #### [For All Users](https://kb.katalys.com/kb/for-all-users.md) #### [Katalys Integrations](https://kb.katalys.com/kb/integrations-with-e-commerce-platforms.md) --- language: "en" --- # Adding a Member to Your Organization (Advertiser) An Admin user can easily add a member to their organization by clicking the 'Invite Members' buttons... ...found on almost every platform page: ![image-20230410-153815.png](https://kb.katalys.com/__attachments/a_37c4fabfaa7c4675cfbdd23652be8ce9356496efdb36093539a4fe15d8b2a831/image-20230410-153815.png?cb=35e3cc4343df39df760ef0547634c19e) ...found specifically on the Members page: ![image-20230410-153929.png](https://kb.katalys.com/__attachments/a_24959aa46e0f7da221f868c54f718779a4cba396893a587dbcf4819968f25769/image-20230410-153929.png?cb=80f44c37ffe1f1df7800499aae0aeb62) From the Invite Members panel that appears, you can add an email *or a list*of emails, and set the new users' role. ![image-20230410-160008.png](https://kb.katalys.com/__attachments/a_a2e262e388349a3da398514b4ed7771f10f7664df1817a355e1cde46d6fc0205/image-20230410-160008.png?cb=7b7c1a5f16f8c85506a2c4cd21bd30ea) Paste in a list, and click out of the email field to prepare an invitation for many users at once! Once invited, a new member of your organization will be sent an invitation to the email address you provide for them. See [**here**](https://kb.katalys.com/kb/user-roles-admin-member-guest.md) for a short list of available user roles and their descriptions! [**Back to User Guide for Advertisers**](https://kb.katalys.com/kb/katalys-marketing-user-guide-for-advertisers.md) --- language: "en" --- # Adding a Member to Your Organization (Partner) An Admin user can easily add a member to their organization by clicking the 'Invite Members' buttons... ...found on almost every platform page: ![image-20230410-153815.png](https://kb.katalys.com/__attachments/a_d2f978030f37673fb2539325c7bea773b05b7b9d791e6d5d7e248e9ab65bffab/image-20230410-153815.png?cb=35e3cc4343df39df760ef0547634c19e) ...found specifically on the Members page: ![image-20230410-153929.png](https://kb.katalys.com/__attachments/a_5719d8ea61e7f570ee7baf7e4f6d93a8090b9d2b22d1c982684a69425a91e77b/image-20230410-153929.png?cb=80f44c37ffe1f1df7800499aae0aeb62) From the Invite Members panel that appears, you can add an email *or a list*of emails and set the new users' roles. ![image-20230410-160008.png](https://kb.katalys.com/__attachments/a_8bae1189548b10e0e070e1bcc18e141551bc5aaf0c15723ed71b9d6e3199a179/image-20230410-160008.png?cb=7b7c1a5f16f8c85506a2c4cd21bd30ea) Paste in a list, and click out of the email field to prepare an invitation for many users at once! Once invited, a new member of your organization will be sent an invitation to the email address you provide for them. See [**here**](https://kb.katalys.com/kb/user-roles-for-affiliates-admin-member.md) for a short list of available user roles and their descriptions! [**Back to User Guide for Partners**](https://kb.katalys.com/kb/katalys-marketing-user-guide-for-affiliates.md) --- language: "en" --- # Advertiser Dashboard Dashboard is a start page in Katalys Marketing Platform. It comprises the analytics information about your performance. You can drill down into analytics as well as customize your performance reports, using the [Reports: Statistics](https://kb.katalys.com/kb/reports-statistics.md) and [Reports: Conversions](https://kb.katalys.com/kb/reports-conversions.md) sections. ![Screenshot 2026-04-28 at 5.37.46 PM.png](https://kb.katalys.com/__attachments/a_d4a16f1c4a08868869e64e44ca3ca82436f3008a27451b271b91e478ac60d184/Screenshot%202026-04-28%20at%205.37.46%E2%80%AFPM.png?cb=e37bd21aed569538a815910dc5a5ff80) Explanation of a graph on the dashboard. ## Dashboard: General View Dashboard presents all the general performance metrics in tables and diagrams: ![image-20240705-114923.png](https://kb.katalys.com/__attachments/a_3f071636e5117f920a760e5602bb677325550cc82d89e973be9f30b63725c848/image-20240705-114923.png?cb=c1d8553f0e76af07ae64cc896845c013) You can adjust the timeframe of the dashboard, using the top right panel: ![image-20240705-115049.png](https://kb.katalys.com/__attachments/a_14af5917b6e7e11a2c998379e2d6b3d4b685153e9e8f8ebe72d2d61782cec1ae/image-20240705-115049.png?cb=ecb183c2fc1efcf53a6d6e546a805e4b) All the diagrams support previewing the values on hovering over the chosen data point: ![image-20240705-115254.png](https://kb.katalys.com/__attachments/a_756f412e17d7023032115cc96f0d39ffcb77aecad29376632f1c78b2b2f7ac26/image-20240705-115254.png?cb=766e4ce3ad20b9a4b8a6b0768d4415da) Question mark icons ![image-20240705-104810.png](https://kb.katalys.com/__attachments/a_43018506b77508759b1599301e9a7279f1fa9f7ef8635a80fe0cf6de8bd6ec2b/image-20240705-104810.png?cb=e7d7e707be9f330ad64b643a196c8445) next to each header describe which metric this diagram or table is dedicated to: ![image-20240705-104726.png](https://kb.katalys.com/__attachments/a_2dcebfc905842ff7a423f104ece5afe583949f31537eb2b3591a22317b5597fc/image-20240705-104726.png?cb=b66d00945fec19ab9af6f109bd64e6a8) Tables support internal sorting (click arrow icon in the corresponding column to sort the table ascending ![image-20240705-105656.png](https://kb.katalys.com/__attachments/a_86f912e5653284479a8e7850509ed561118dfc423c0cf1a72c68563ad9bcb955/image-20240705-105656.png?cb=3e5fcdfaf9923925f59fcbe778ccd707) and descending ![image-20240705-105725.png](https://kb.katalys.com/__attachments/a_43155c7fd99af72789552323c21de0839a8ec232d94c926b9e06fdae393615ff/image-20240705-105725.png?cb=a77ad50cc76eb390f5e63b3addd454bf) ). Trend icon ![image-20240705-104924.png](https://kb.katalys.com/__attachments/a_071e8e662ed13e45e7fe6b0f38709d97e407a89a1336b5a582df1f1028e0af9a/image-20240705-104924.png?cb=73f9e5159248d4944be2df64f54013be) in the tables redirects to the [report](https://kb.katalys.com/kb/reports-statistics.md), applying the corresponding filters for more detailed review: ![image-20240705-115156.png](https://kb.katalys.com/__attachments/a_b536475b2a7a629dd0878398b1b62c7366c70f618f18b5a9aae5297c015b4392/image-20240705-115156.png?cb=18f7f1d47316a22d49c4b5b45b70cbae) ![image-20240705-114737.png](https://kb.katalys.com/__attachments/a_e030e5f82f9f617bd30590b7e07fe538ddf80659179fba61278e373c778ab958/image-20240705-114737.png?cb=6b75e1fea4a21b06cac80f0df996a200) --- language: "en" --- # Advertiser Terms & Conditions The full Advertiser Terms \& Conditions are published on our website and linked below. The Advertiser Terms \& Conditions govern how Katalys works with Advertisers. This agreement explains how we work together --- launching campaigns, using the platform, billing, account access, and staying compliant with our policies. [**Read our Advertiser Terms \& Conditions**](https://katalys.com/legal/platform-terms-and-conditions/)**-\>** Katalys also has a published policy on how Katalys handles privacy and data collection so that Katalys can fulfill our contracts. [**Read our Privacy Policy**](https://katalys.com/legal/privacy-policy/)**-\>** ## **What's Covered** These terms and policies cover: * Ad Campaign Execution * Ad Approval \& Restrictions * Account Responsibilities * Billing \& Payment Terms * Fraud Prevention * Email Compliance * Data Rights \& Confidentiality * Intellectual Property * Reporting \& Valid Actions * Termination \& Ownership * Legal Protections ### **When to Use This Page** Use this page to quickly reference the terms, responsibilities, and key details of your relationship with Katalys as an advertiser. Have questions? [Contact support](https://kb.katalys.com/kb/submitting-feedback-and-reporting-errors.md). --- language: "en" --- # Compare Performance Between Date Ranges The Katalys platform offers the ability to pull custom reports on the Performance page between two individually-selected date ranges by enabling the "Compare" toggle. To use this feature, please follow these steps: 1. Go to the Performance page 2. Turn off Comparison and select Custom 3. Change the range by selecting a new start and end date. Notice the comparison range updates, as well. 4. Pick a start date before the comparison start date. Notice the comparison start date is moved to before the start date. Check out the below video to see how to use the date-range Compare feature! [++**Back to User Guide for Partners**++](https://kb.katalys.com/kb/katalys-marketing-user-guide-for-affiliates.md) --- language: "en" --- # Analytics: Conversions Report * [Conversion Report - Data Glossary for Partners](https://kb.katalys.com/kb/conversion-reports-data-glossary.md) * [Compare Performance Between Date Ranges](https://kb.katalys.com/kb/affiliate-comparing-performance-between-date-range.md) ![image-20240708-132344.png](https://kb.katalys.com/__attachments/a_26a7e41189b43af92a22ca57b402b575123f3de8afc0a994626623cc1bd82300/image-20240708-132344.png?cb=f37dfe116d376f65c01467bb96888656) --- language: "en" --- # API Access The Katalys API allows you to run Statistics and Conversions reports against your data housed with the Katalys system. This enables Partners and Advertisers to ingest data into their data warehouses. [Read more about the Data Warehousing use case →](https://kb.katalys.com/kb/api-use-case-data-warehousing.md) ## Available Endpoints All endpoints require you to have an API key that you can retrieve via the KMP platform. [Read how to get your API key →](https://kb.katalys.com/kb/api-authentication.md) The following API endpoints are available for use: * [Statistics Reports](https://kb.katalys.com/kb/api-endpoint-statistics-reports.md). Used for generating summation statistics against the traffic you send or receive from the Katalys network. * [Conversion Reports](https://kb.katalys.com/kb/api-endpoint-conversion-report.md). Used for generating order reports for postbacks, recons, or granular reporting on order values. ## Legacy API In addition to our owned+operated API, Katalys syncs your data into a Tune API system. If they already use Tune in their existing tech stack, this is sometimes easier for Partners . *This system has known limitations!* --- language: "en" --- # API Authentication Requests to the Katalys API requires that you generate an API key for for your organization. The API key will have read/write access to your all data owned by your Organization. * An Organization owns one or more Profiles. Permissions are managed per-Organization. * A Profile owns one or more Programs and/or Traffic Sources. Profiles hold brand information like your profile, and your integrations which hold your data. ## Generating an API Key To generate an API key, login to your KMP account, click "Settings" in the main-navigation bar, and click "API Access". Or use the link below. [**Get your API key now →**](https://app.katalys.com/_/_/settings/apikeys) Retrieving an API key is a sensitive action. You must be an Admin-level user within your Organization to manage or view API keys. ## Authenticating to the API Once you have generated an API key, include that key within the `Authorization` header of every HTTP request you make to the Katalys API. The syntax for the `Authorization` header is `apikey {your-api-key}`. An example API call might be: curl -i -H 'Authorization: apikey 123456789abcdef@12345-6789-abcdef-abcdef' \ -H 'Content-Type: application/json' \ -d '{"dimensions": ["order_time", "order_id", "payout"], "filters": [ {"field":"time", "type":"range", "values":[12345, 12346] } ] }' \ https://api.katalys.com/v1/report/conversions If you are having issues seeing the data you expect, please refer to the [API Debugging Guide](https://kb.katalys.com/kb/debugging-api-responses.md). ## Rate Limits Your API key is limited to 30 requests per minute. If you exceed this, you will start receiving HTTP 429 responses, and you must pause usage of the key for a full minute before continuing to use your API key. [Next Page](https://kb.katalys.com/llms-full.txt/1)