Kwikk API Documentation for Developers

Welcome to our public documentation page. To read more about our services, please visit our website Kwikk.se.

Getting Started

The API follows a rather simple structure that is largely independent on the type of resource you request. Note that the API is mainly used for reading data from Kwikk - inserting information is done by creating purchase buttons and placing orders.

There is also a front-end API that allows your application to react to events in the Kwikk checkout. Read more about it in the section JS Events.

Make a request

To make a request to the public API endpoint you will need two items.

First, you will need a url of the form:
https://api.kwikk.se/public/[TYPE]/[PARAMETERS]

Where valid options for the [TYPE] and [PARAMETER] components can be found in the Request Types section of this document.
Second, you will need your user specific API access key. This can be found by logging into your Kwikk admin portal and navigating to My Profile (Min Profil) > Developer Information () > API Access Key ().

PHP example

For php systems, requests to the public API endpoint can be made using cURL.

The target url is described in the Input section of this document. Your key also needs to be included as a POST element, under the label key. If successful, you will be returned a stringified JSON array containing the requested data.

A simple example:


$url = ‘https://api.kwikk.se/public/orders/’;
$key = [YOUR API KEY];
$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,array('key'=>$key));
$ch_return = curl_exec($ch);
$result = json_decode($ch_return, true);
curl_close ($ch);

API Call Types

Button/Buttons

The button type will return a JSON array containing between 0 and 1000 (default 20) of your buttons. If a button ID is placed in the [PARAMETERS] component, then only that button will be returned.

Example:
https://api.kwikk.se/public/button/1

Filters
Any number of GET-formatted filters may also be placed in the [PARAMETERS] component. This table lists all of the valid parameters for the ‘button’ type and gives details on their function.

Example:
https://api.kwikk.se/public/button?button_artno=TestArticle

Filter name Format Details
button_id [INT] Fetches the butotn matching the ID
button_artno [STRING] Makes a partial match against the button article number
button_title [STRING] Makes a partial match against the button title
button_description [STRING] Matches against button description
button_price_from [DOUBLE] Returns any buttons over the set price.
button_price_to DOUBLE Returns any buttons under the set price.
button_vat_from [DOUBLE] Returns any buttons under the set vat.
button_vat_to [DOUBLE] Returns any buttons over the set vat.
button_inactive [0-1] Filters on if a button is active (0) or inactive (1)
results_limit [0-9] Return up to X results. Minimum 1 and maximum 1000.
results_offset [0-9] Skip the first X results.
results_sort “button_id”,
“button_artno”,
“button_title”,
“button_price”,
“button_id_desc”,
“button_artno_desc”,
“button_title_desc”,
“button_price_desc”		 The variable to order results by.

Order/Orders

The orders type will return a JSON array containing between 0 and 1000 (default 20) of your most recent orders. If an order ID is placed in the [PARAMETERS] component, then only that order will be returned.

Example:
https://api.kwikk.se/public/order/1000

Filters
Any number of GET-formatted filters may also be placed in the [PARAMETERS] component. This table lists all of the valid parameters for the ‘orders’ type and gives details on their function.

Example:
https://api.kwikk.se/public/order?order_date_lower=2021-01-01+23:59:59&order_price=1000

Filter name Format Details
customer_name [STRING] Makes a partial match against the name provided by the buyer at the time of sale.
customer_phone [+0-9] Makes a partial match against the phone number provided by the buyer at the time of sale.
customer_email [STRING] Makes a partial match against the email address provided by the buyer at the time of sale.
customer_id [0-9] Makes a partial match against the unique Kwikk ID of the customer.
order_artnr [STRING] Makes a partial match against the article numbers of the order, the article numbers or product names of any products contained within the order.
order_comment [STRING] Makes a partial match against the comment provided by the buyer at the time of sale.
order_type [STRING] The order type LIVE for live orders, or TEST for test orders
order_date_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns orders placed after the chosen date and time.
order_date_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns orders placed before the chosen date and time.
order_date_paid_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns orders paid after the chosen date and time.
order_date_paid_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns orders paid before the chosen date and time.
order_id [0-9] Makes an exact match the unique Kwikk order ID.
order_payment_method “SWISH”,
“CARD_EU”, “MANUAL”		 Makes an exact match against the text payment method code.
order_payout_date_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns orders paid out after the chosen date and time.
order_payout_date_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns orders paid out before the chosen date and time.
order_payment_status [STRING] Paymentstatus of the order PAID for a paid order, DECLINED for an unsuccessful order
order_price [.0-9] Makes an exact match against the total order price.
order_price_lower [.0-9] Returns orders with a total order price greater than the chosen value.
order_price_upper [.0-9] Returns orders with a total order price less than the chosen value.
order_state [STRING] Makes an exact match against the order state ID or the order state name. These are created and managed in the Kwikk backend.
order_print_status "false",
"printed",
"force"		 Makes an exact match against the print status of the order. "false" means it hos not been printed yet, "printed" means it has been printed, and "force" means it has been triggered manually to get printed again.
order_vat_lower [.0-9] Returns orders with a total order vat (tax) greater than the chosen value.
order_vat_upper [.0-9] Returns orders with a total order vat (tax) less than the chosen value.
order_not_refunded 1 Returns only orders that have not been refunded.
order_custom_data [STRING] Returns orders matching the custom data provided
product_artnr [STRING] Makes a partial match against the article numbers of the order, the article numbers or product names of any products contained within the order.
product_title [STRING] Makes a partial match against the article numbers of the order, the article numbers or product names of any products contained within the order.
results_limit [0-9] Return up to X results. Minimum 1 and maximum 1000.
results_offset [0-9] Skip the first X results.
results_sort “order_id”,
“order_artnr”,
“order_price”		 The variable to order results by.

The downloads type will return a JSON array containing between 0 and 1000 (default 20) of your downloadable items. If a download ID is placed in the [PARAMETERS] component, then only that downloadable item will be returned.

Example:
https://api.kwikk.se/public/download/1

Filters
Any number of GET-formatted filters may also be placed in the [PARAMETERS] component. This table lists all of the valid parameters for the ‘download’ type and gives details on their function.

Example:
https://api.kwikk.se/public/download?download_date_created_lower =2021-01-01+23:59:59&download_link_count_all_lower=1

Filter name Format Details
download_active [01] Returns only downloadable items that are marked as active. This does not necessarily mean there are any existing or active download links to this item.
download_date_created_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns downloadable items created after the chosen date and time.
download_date_created_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns downloadable items created before the chosen date and time.
download_date_recent [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Sets the lower limit of the date range used to generate ‘recent’ download counts. Defaults to 1 month prior to the current date.
download_downloads_count_all [0-9] Returns downloadable items which have a total number of downloads equal to the chosen value.
download_downloads_count_all_lower [0-9] Returns downloadable items which have a total number of downloads greater than or equal to the chosen value.
download_downloads_count_all_upper [0-9] Returns downloadable items which have a total number of downloads less than or equal to the chosen value.
download_downloads_count_recent [0-9] Returns downloadable items which have a total number of recent downloads equal to the chosen value. The date range for ‘recent’ downloads defaults to the last month, but can be set using the ‘download_date_recent’ parameter.
download_downloads_count_recent_lower [0-9] Returns downloadable items which have a total number of recent downloads greater than or equal to the chosen value. The date range for ‘recent’ downloads defaults to the last month, but can be set using the ‘download_date_recent’ parameter.
download_downloads_count_recent_upper [0-9] Returns downloadable items which have a total number of recent downloads less than than or equal to the chosen value. The date range for ‘recent’ downloads defaults to the last month, but can be set using the ‘download_date_recent’ parameter.
download_file_name [STRING] Makes a partial match against the downloadable item current file name.
download_id [0-9] Makes an exact match against the downloadable item unique Kwikk ID.
download_link_count_all [0-9] Returns downloadable items which have a total number of download links equal to the chosen value.
download_link_count_all_lower [0-9] Returns downloadable items which have a total number of download links greater than or equal to the chosen value.
download_link_count_all_upper [0-9] Returns downloadable items which have a total number of download links less than or equal to the chosen value.
download_link_count_current [0-9] Returns downloadable items which have a total number of currently active download links equal to the chosen value. Active links are ones that have not yet expired and have not reached their download limit.
download_link_count_current_lower [0-9] Returns downloadable items which have a total number of currently active download links greater than or equal to the chosen value. Active links are ones that have not yet expired and have not reached their download limit.
download_link_count_current_upper [0-9] Returns downloadable items which have a total number of currently active download links less than or equal to the chosen value. Active links are ones that have not yet expired and have not reached their download limit.
download_link_count_recent [0-9] Returns downloadable items which have a total number of recently created download links equal to the chosen value. The date range for ‘recent’ downloads defaults to the last month, but can be set using the ‘download_date_recent’ parameter.
download_link_count_recent_lower [0-9] Returns downloadable items which have a total number of recently created download links greater than or equal to the chosen value. The date range for ‘recent’ downloads defaults to the last month, but can be set using the ‘download_date_recent’ parameter.
download_link_count_recent_upper [0-9] Returns downloadable items which have a total number of recently created download links less than or equal to the chosen value. The date range for ‘recent’ downloads defaults to the last month, but can be set using the ‘download_date_recent’ parameter.
download_link_id [0-9] Returns downloadable items that contain a link with a unique download ID link equal to the chosen value.
download_maximum_link_count [0-9] Returns downloadable items which have a maximum number of download attempts equal to the chosen value.
download_maximum_link_count_lower [0-9] Returns downloadable items which have a maximum number of download attempts greater than or equal to the chosen value.
download_maximum_link_count_upper [0-9] Returns downloadable items which creates download links that have a maximum number of download attempts less than or equal to the chosen value.
download_maximum_link_duration [0-9] Returns downloadable items which creates download links that are active for a number of days equal to the chosen value.
download_maximum_link_duration_lower [0-9] Returns downloadable items which creates download links that are active for a number of days greater than or equal to the chosen value.
download_maximum_link_duration_upper [0-9] Returns downloadable items which creates download links that are active for a number of days less than or equal to the chosen value.
download_title [STRING] Makes a partial match against the downloadable item’s currently assigned name/title.
order_artnr [STRING] Returns downloads that contain orders with an article number equal to the chosen value. Only these orders will be listed.
order_customer_email [STRING] Returns downloads that contain orders with a customer email address that partially matches the chosen value. Only these orders will be listed.
order_customer_name [STRING] Returns downloads that contain orders with a customer name that partially matches the chosen value. Only these orders will be listed.
order_customer_phone [+0-9] Returns downloads that contain orders with a customer phone number that partially matches the chosen value. Only these orders will be listed.
order_id [0-9] Returns downloads that contain orders with an order id equal to the chosen value. Only these orders will be listed.
order_price [.0-9] Returns downloads that contain orders with a total order price equal to the chosen value.
results_limit [0-9] Return up to X results. Minimum 1 and maximum 1000.
results_offset [0-9] Skip the first X results.
results_sort “download_id”,
“download_title”		 The variable to order results by.

Register/Registers

The register type will return a JSON array containing between 0 and 1000 (default 20) of your customer records. If a register ID is placed in the [PARAMETERS] component, then only that customer’s data will be returned.

Example:
https://api.kwikk.se/public/register/10000

Filters
Any number of GET-formatted filters may also be placed in the [PARAMETERS] component. This table lists all of the valid parameters for the ‘register’ type and gives details on their function.

Example:
https://api.kwikk.se/public/register?register_name=test+name&register_personnumber=123456789

Filter name Format Details
register_account_number [-0-9] Makes a partial match against the customer’s account number.
register_address [STRING] Makes a partial match against the customer’s street address.
register_city [STRING] Makes a partial match against the customer’s city.
register_company [STRING] Makes a partial match against the customer’s company name.
register_email [STRING] Makes a partial match against the customer’s email.
register_id [0-9] Makes an exact match against the customer’s unique Kwikk ID.
register_name [STRING] Makes a partial match against the customer’s first or last name.
register_name_first [STRING] Makes a partial match against the customer’s first name.
register_name_last [STRING] Makes a partial match against the customer’s last name.
register_note [STRING] Makes a partial match against the note about the customer.
register_critical_note [STRING] Makes a partial match against the critical note about the customer.
register_personnumber [0-9] Makes an exact match against the customer’s personnumber.
register_phone [+0-9] Makes a partial match against the customer’s phone number.
register_zip [0-9] Makes an exact match against the customer’s zip code.
register_active [01] Returns only registers that are marked as active.
register_member [01] Returns only registers that are marked as members.
results_limit [0-9] Return up to X results. Minimum 1 and maximum 1000.
results_offset [0-9] Skip the first X results.
results_sort “register_name_first”,
“register_name_last”,
“register_company”,
“register_email”,
“register_personnumber”		 The variable to order results by.

Repeat/Repeating (DEPRECATED)

This type is deprecated and will be removed in the future.

The repeat type will return a JSON array containing between 0 and 1000 (default 20) of your most recently created repeating payments. If a repeating payments ID is placed in the [PARAMETERS] component, then only that repeating payment will be returned.

Example:
https://api.kwikk.se/public/repeat/1

Filters
Any number of GET-formatted filters may also be placed in the [PARAMETERS] component. This table lists all of the valid parameters for the ‘repeat’ type and gives details on their function.

Example:
https://api.kwikk.se/public/repeat?repeating_date_start_lower=2021-01-01_23:59:59&repeating_price_lower=1000

Filter name Format Details
repeating_artnr [STRING] Makes a partial match against the article number stored with the repeating payment. Unless edited, this will be the article number of the original product.
repeating_date_due_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns repeating payments with their next payment due after the chosen date and time.
repeating_date_due_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns repeating payments with their next payment due before the chosen date and time.
repeating_date_expires_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns repeating payments which will expire if not paid after the chosen date and time.
repeating_date_expires_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns repeating payments which will expire if not paid before the chosen date and time.
repeating_date_start_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns repeating payments initially purchased after the chosen date and time.
repeating_date_start_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns repeating payments initially purchased before the chosen date and time.
repeating_id [0-9] Makes an exact match against the unique Kwikk repeating payments id.
repeating_note [STRING] Makes a partial match against the repeating payment’s note.
repeating_price [.0-9] Makes an exact match against the price stored with the repeating payment. Unless edited, this will be the price of the original product.
repeating_price_lower [.0-9] Returns repeating payments with a stored price greater than or equal to the chosen value.
repeating_price_upper [.0-9] Returns repeating payments with a stored price less than or equal to the chosen value.
repeating_register_id [0-9] Makes an exact match against the unique Kwikk register id to whom the repeating payment is allocated.
repeating_title [STRING] Makes a partial match against the product name/title stored with the repeating payment. Unless edited, this will be the name/title of the original product.
results_limit [0-9] Return up to X results. Minimum 1 and maximum 1000.
results_offset [0-9] Skip the first X results.
results_sort “repeating_date_start”,
“repeating_date_due”,
“repeating_date_expires”,
“repeating_price”,
“repeating_title”,
“repeating_artnr”		 The variable to order results by.

Subscription/Subscriptions

The subscription type will return a JSON array containing between 0 and 1000 (default 20) of your most recently created subscriptions. If a subscription ID is placed in the [PARAMETERS] component, then only that subscription will be returned.

Example:
https://api.kwikk.se/public/subscription/1

Filters
Any number of GET-formatted filters may also be placed in the [PARAMETERS] component. This table lists all of the valid parameters for the ‘repeat’ type and gives details on their function.

Example:
https://api.kwikk.se/public/subscription?subscription_title=test+subscription&subscription_customer=test+customer

Filter name Format Details
subscription_title [STRING] Makes a partial match against the product name/title stored with the repeating payment. Unless edited, this will be the name/title of the original product.
subscription_note [STRING] Makes a partial match against the note about the subscription.
subscription_customer [STRING] Makes a partial match against the customer name.
subscription_customer_id [0-9] Makes an exact match against the unique Kwikk register id to whom the repeating payment is allocated.
subscription_customer_email [STRING] Makes a partial match against the customer email.
subscription_customer_name [STRING] Makes a partial match against the customer name.
subscription_status [1234] Makes an exact match against the subscription status. 1 - Active, 2 - Active, but not activated 3 - Active and activated 4 - Inaktive
subscription_ongoing [01] Returns subscriptions that are ongoing.
subscription_date_created_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns subscriptions that were initially created after the chosen date and time.
subscription_date_created_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns subscriptions that were initially created before the chosen date and time.
subscription_date_activation_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns subscriptions that were activated after the chosen date and time.
subscription_date_activation_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns subscriptions that were activated before the chosen date and time.
subscription_date_deactivation_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns subscriptions that were deactivated after the chosen date and time.
subscription_date_deactivation_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns subscriptions that were deactivated before the chosen date and time.
subscription_date_due_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns subscriptions with their next payment due after the chosen date and time.
subscription_date_due_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns subscriptions with their next payment due before the chosen date and time.
subscription_date_expires_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns subscriptions which will expire if not paid after the chosen date and time.
subscription_date_expires_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns subscriptions which will expire if not paid before the chosen date and time.
subscription_price_lower [0-9] Returns subscriptions with a price greater than or equal to the chosen value.
subscription_price_upper [0-9] Returns subscriptions with a price less than or equal to the chosen value.
subscription_artnr [STRING] Makes a partial match against the article number stored with the subscription. Unless edited, this will be the article number of the original product.
results_offset [0-9] Skip the first X results.
results_limit [0-9] Return up to X results. Minimum 1 and maximum 1000.

Instance/Instances

The instance type will return a JSON array containing between 0 and 1000 (default 20) of your most recently created instances. If a instance ID is placed in the [PARAMETERS] component, then only that instance will be returned.

Example:
https://api.kwikk.se/public/instance/1

Filters
Any number of GET-formatted filters may also be placed in the [PARAMETERS] component. This table lists all of the valid parameters for the ‘repeat’ type and gives details on their function.

Example:
https://api.kwikk.se/public/instance?instance_label=test+instance

Filter name Format Details
instance_id [0-9] Makes an exact match against the unique Kwikk instance id.
instance_register_key [STRING] Makes a partial match against the register key of the customer associated with the instance.
instance_subscription_id [0-9] Makes an exact match against the unique Kwikk subscription id to which the instance is allocated.
instance_due_from_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns instances that are due from the chosen date and time.
instance_due_from_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns instances that are due from the chosen date and time.
instance_expires_lower [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns instances that are expired after the chosen date and time.
instance_expires_upper [YY-MM-DD]
[YY-MM-DD+HH:MM:SS]		 Returns instances that are expired after the chosen date and time.
instance_auto_attempts_lower [0-9] Returns instances with a number of auto attempts greater than or equal to the chosen value.
instance_auto_attempts_upper [0-9] Returns instances with a number of auto attempts less than or equal to the chosen value.
instance_cancelled [01] Returns instances that are cancelled.
instance_paid [01] Returns instances that are paid.
instance_is_automatic_payment [01] Returns instances that are automatic payments.
instance_manual_pending_payment [01] Returns instances that are manual pending payments.
instance_exclude_instances_with_manual_payments [01] Returns instances that are not manual pending payments.
instance_timeframe_unit [STRING] Returns instances that are in the chosen timeframe unit.
instance_prepay_flagged [01] Returns instances that are prepay flagged.
instance_prepay_not_flagged [01] Returns instances that are not prepay flagged.
results_offset [0-9] Skip the first X results.
results_limit [0-9] Return up to X results. Minimum 1 and maximum 1000.

Request/Requests

The requests type will return a JSON array containing between 0 and 1000 (default 20) your payment requests sent out to customers. If a request ID is placed in the [PARAMETERS] component, then only that payment request will be returned.

Example:
https://api.kwikk.se/public/request/1

Filters
Any number of GET-formatted filters may also be placed in the [PARAMETERS] component. This table lists all of the valid parameters for the ‘request’ type and gives details on their function.

Example:
https://api.kwikk.se/public/request?request_date_created_lower=2021-01-01+23:59:59&request_link_id=test+payment+requests

Filter name Format Details
register_account_number [-0-9] Makes a partial match against the customer’s account number.
register_address [STRING] Makes a partial match against the customer’s street address.
register_city [STRING] Makes a partial match against the customer’s city.
register_company [STRING] Makes a partial match against the customer’s company name.
register_email [STRING] Makes a partial match against the customer’s email.
register_id [0-9] Makes an exact match against the customer’s unique Kwikk ID.
register_name [STRING] Makes a partial match against the customer’s first or last name.
register_name_first [STRING] Makes a partial match against the customer’s first name.
register_name_last [STRING] Makes a partial match against the customer’s last name.
register_note [STRING] Makes a partial match against the note about the customer.
register_critical_note [STRING] Makes a partial match against the critical note about the customer.
register_personnumber [0-9] Makes an exact match against the customer’s personnumber.
register_phone [+0-9] Makes a partial match against the customer’s phone number.
register_zip [0-9] Makes an exact match against the customer’s zip code.
register_active [01] Returns only registers that are marked as active.
register_member [01] Returns only registers that are marked as members.
results_limit [0-9] Return up to X results. Minimum 1 and maximum 1000.
results_offset [0-9] Skip the first X results.
results_sort “register_name_first”,
“register_name_last”,
“register_company”,
“register_email”,
“register_personnumber”		 The variable to order results by.

API Error Codes

Access Errors

101: No API key provided. Your API key must be sent through as a POST variable. Details on how to find your API key can be found in the Getting Started section of this document.

102: API key does not identify the user. Please make sure your API key exactly matches the one found using the instructions in the Getting Started section of this document. If this error persists, please contact a Kwikk staff member.

103: API key is incorrect. Please make sure your API key exactly matches the one found using the instructions in the Getting Started section of this document.

104: No API access type included. URLS must be of the form https://api.kwikk.se/public/[TYPE]/[PARAMETERS]. A [TYPE] component is mandatory.

Permissions Errors

201: API access has been disabled for the user. This occurs when an unexpectedly high volume of requests happens within a small time period. Please contact a Kwikk staff member to have this permission reinstated.

Filter Errors

301: Invalid results_sort value. Please ensure the sorting filter you have entered is listed as a valid option on the associated filter table found in the API Call Types section of this document.

Results Errors

401: No results found. This could be because a filter is invalid or because no results match the filters chosen.

JS Events (front-end API)

When the user interacts with the Kwikk checkout, javascript events are triggered on the Window object. These events also carries a "details" payload to facilitate any reactions to the events.

Please note that these events are only triggered in the browser of the user (front-end), not on the server-side (back-end).

If you have any questions, need help with the implementation, or find a bug - don't hesitate to contact us at hej@kwikk.se.

Listen to JS events

When users interact with your Kwikk checkout, various JavaScript events are triggered, which can be listened to for performing actions such as analytics tracking or updating your UI in response to these interactions. Here's how you can listen to these events in your JavaScript code.

Basic example

// Listen to the `kwikk.order.complete` event for order completion
window.addEventListener('kwikk.order.complete', function(e) {
    var details = e.detail; // Access the event's details
    console.log('Order completed:', details);

    // Here, you can integrate with analytics or other services
    // For example, send this data to Google Analytics 4 (GA4) or Meta Pixel
});

Event details

The details are different for each event type. See event payloads in the table below. Here is an example for the kwikk.order.complete event:

{
  "orderkey": "10002x1534",
  "cart": [
    {
      "artnr": "keps",
      "price": 100,
      "title": "Keps",
      "desc": "A cool and trendy hat for the top of your head!",
      "vat_amount": 20,
      "ticket": "false",
      "repeating": "false",
      "config_settings": [],
      "calendar_data": false,
      "sellerid": "10002"
    }
  ],
  "price": 100,   // Total price inc. tax for the order
  "vat": 20,      // Total tax amount
  "shipping": 40, // Total shipping cost inc. tax
  
  // Customer details
  "phone": "+46700000000",
  "name": "Firstname Lastname",
  "address": "Church street 1",
  "postal": "792 00",
  "city": "Mora"
}

Tracking for ads

For ad tracking, focusing on order completion, you'll want to capture the kwikk.order.complete event and then send the relevant data to your ad platforms like GA4 and Meta for conversion tracking.

Please note that these examples were updated in March 2024.

Google Analytics 4 (GA4) Tracking

For GA4, you'll need to send an event with the order details. Assuming you've already set up GA4 on your website, here's how you can track order completions:

window.addEventListener('kwikk.order.complete', function(e) {
    var details = e.detail;

    // Sending order completion event to GA4
    gtag('event', 'purchase', {
        "transaction_id": details.orderkey, // The Kwikk order id, [merchant id]x[order id]
        "value": details.price,
        "currency": "SEK", 
        "tax": details.vat,
        "shipping": details.shipping, // Add your shipping cost here
        "items": details.cart.map(item => { 
            "item_id": item.artnr,   // Required by GA4
            "item_name": item.title, // Required by GA4
            "price": item.price,     // Not required by GA4
        })
    });
});

Meta (Facebook Pixel) Tracking

For tracking conversions with Meta, you'll similarly capture the order completion event and send the details to Meta using the fbq function:

window.addEventListener('kwikk.order.complete', function(e) {
    var details = e.detail;

    // Sending order completion event to Meta Pixel
    fbq('track', 'Purchase', {
        value: details.price,
        currency: 'SEK', // Replace with your currency code
        content_type: 'product', // Assuming you're selling products
        content_ids: details.cart.map(item => item.artnr), // Assuming each item in `cart` has an `id`
        tax: details.vat,
        shipping_amount: details.shipping // Add your shipping cost here
    });
});

List of events

Events are triggered on the Window object.

Event name Description Event details
kwikk.order.complete Order and payment was completed 
{
    "cart": "(list of articles in cart)",
    "price": 80,
    "vat": 20,
    "shipping": 10,
    "phone": "(customer phone)",
    "name": "(customer name)",
    "address": "(customer address)",
    "postal": "(customer postal)",
    "city": "(customer city)"
}
kwikk.ready Ready event occurred 
null
kwikk.cart.add Article was added to cart 
{
    "target": "(DOM element of the button triggering the event)",
    "dataset": "(parameters for the added article)",
    "cart": "(list of articles in cart)"
}
kwikk.cart.update Cart was updated by adding or removing an article 
{
    "cart": "(list of articles in cart)"
}
kwikk.cart.show Cart is shown 
{
    "cart": "(list of articles in cart)"
}
kwikk.cart.calculate Cart was calculated 
{
    "cart": "(list of articles in cart)"
}
kwikk.popup.close Popup was closed 
{
    "orderStatus": "(order status)"
}
kwikk.lookup.init Phone-based address lookup was initialized 
{
    "cart": "(list of articles in cart)",
    "price": "(order value including taxes)"
}
kwikk.lookup.complete Phone-based address lookup completed successfully 
{
    "match": false,
    "cart": "(list of articles in cart)",
    "price": "(order value including taxes)",
    "phone": " (customer phone)"
}
kwikk.lookup.complete Phone-based address lookup completed without a match 
{
    "match": true,
    "cart": "(list of articles in cart)",
    "price": "(order value including taxes)",
    "phone": "(customer phone)",
    "name": "(customer name)",
    "address": "(customer address)",
    "postal": "(customer postal)",
    "city": "(customer email)"
}
kwikk.lookup.modified Phone-based address lookup result was modified after completion 
{
    "cart": "(list of articles in cart)",
    "price": "(order value including taxes)",
    "vat": "(order tax amount)",
    "phone": "(customer phone)",
    "name": "(customer name)",
    "address": "(customer street address)",
    "postal": "(customer postal)",
    "city": "(customer city)",
    "email": "(customer email)"
}
kwikk.comment.modified Comment/message field was modified 
{
    "cart": "(list of articles in cart)",
    "price": "(order value including taxes)",
    "vat": "(order tax amount)",
    "phone": "(customer phone)",
    "name": "(customer name)",
    "address": "(customer street address)",
    "postal": "(customer postal)",
    "city": "(customer city)",
    "email": "(customer email)"
}
kwikk.order.error Error occurred during order processing 
{
    "error": "(error code)",
    "cart": "(list of articles in cart)",
    "price": "(order value including taxes)",
    "vat": "(order tax amount)",
    "phone": "(customer phone)",
    "name": "(customer name)",
    "address": "(customer street address)",
    "postal": "(customer postal)",
    "city": "(customer city)"
}
kwikk.mail.sent Mail copy of the order was sent to customer 
{
    "email": "(customer email)"
}
kwikk.render.complete Render complete. This event is triggered every time anything changes in frontend data model, which triggers a re-render. We recommend using a debounce function around this event to avoid overloading the browser, depending on what you want to do after the event. 
{
    "time": "(time taken)"
}
kwikk.renderbuttons.complete Render buttons complete. This event is triggered every time the buttons are rendered or re-rendered. 
{
    "time": "(time taken)"
}

JS Functions (front-end API)

We have a number of functions available if you need to act on the cart or cart state. These can be accessed on the kwikk object

List of functions

Functions exist on the Kwikk object.

Function name Description Returns
kwikk.getCartSummary Get the cart summary 
{
    "prodPriceIncVat": 1085,
    "shippingPriceIncVat": false,
    "shippingVatMultiplier": 1,
    "selectedShippingObj": false,
    "totalPrice": 1085,
    "totalVat": 116.25,
    "totalDiscount": 75,
    "totalDiscountPrice": 1010,
    "totalDiscountVat": 202,
    "totalPriceIncShipping": 1085,
    "totalVatIncShipping": 116.25,
    "totalDiscountPriceIncShipping": 1010,
    "totalDiscountVatIncShipping": 202
}
kwikk.getCart List all objects in the cart 
[
    {
        "id": 1,
        "name": "Product 1",
        "price": 100,
        "quantity": 1
    },
    {
        "id": 2,
        "name": "Product 2",
        "price": 200,
        "quantity": 2
    }
]
kwikk.clearCart Removes all items from the cart 
null
kwikk.removeFromCartByIdx Removes an item from the cart by index 
null

Generate buttons

Buttons can be saved ahead of time or generated on-the-fly for dynamic prices, like in a configuration flow where the funal price depends on user selections. Dynamic buttons could also be used when you want to set the SKU (artnr) to a custom value, like the email address of a user, which will allow you to collect a "payment completed" webhook and unlock a user account based on the SKU.

Kwikk buttons are script tags with data attributes. Which attributes to use depends on your needs, but seller and artnr are always required.

Wix and other no-code CMS platforms

Some platforms do not allow (or heavily limit) the use of <script> tags. For such platforms, we've developed a workaround which replaces them with shortcodes like this: (kwikk seller="10001" artnr="soap"). Please get in touch with us at hej@kwikk.se for instructions.

Saved buttons

Merchant can create, duplicate, edit, archive and delete buttons using the Kwikk admin interface at admin.kwikk.se. To display a pre-saved button on a website, you only need to add the data-seller and data-artnr attributes.

<script type="text/javascript" src="https://client.kwikk.se/kwikk-client.js" data-seller="10000" data-artnr="test-article"></script>

Dynamic buttons

Dynamic buttons allow for a more flexible and real-time integration of the Kwikk payment system into your website or application. They are generated programmatically based on specific product and customer information, offering a tailored checkout experience for each user.

To create a dynamic button, you need to generate a unique key using product details, customer information, and optionally, shipping costs. This is done server-side to ensure security and integrity of the transaction.

Key and Seller ID

To generate buttons, you need your seller ID and button generation key. You find both on this page after logging in.

Generating a Dynamic Button

Below is a PHP function that generates a unique hash key based on the provided information:

/**
 * Generate a key based on product and customer information.
 *
 * @param string $customerId       Seller ID, visible at the top-right corner of the admin page after login.
 * @param string $artnr            Unique product ID used for stock management.
 * @param float  $price            Price of the product including VAT.
 * @param float  $vatAmount        Optional. VAT amount in fiat currency (SEK).
 * @param int    $maxSales         Optional. Maximum number of sales for this product.
 * @param string $customerKey      Optional. Customer key, either a 128-char randomized ASCII string or [customer id]-[32-char hex string].
 * @param float  $shippingStandard Optional. Shipping cost for standard shipping excluding VAT.
 * @param float  $shippingExpress  Optional. Shipping cost for express shipping excluding VAT.
 * 
 * @return string A hashed string based on the input parameters.
 */
function kwikk_generate_key($customerId, $artnr, $price, $customerKey, $vatAmount = '', $maxSales = '', $shippingStandard = '', $shippingExpress = ''){

	$inputStr = $customerId . 
		'|' . $artnr . 
		'|' . $price . 
		'|' . $vatAmount . 
		'|' . $maxSales . 
		'|' . $customerKey . 
		'|' . $shippingStandard . 
		'|' . $shippingExpress;
	
	$hash = hash('sha256', $inputStr);
	return $hash;
}

/**
 * Generate a script tag for a Kwikk button using provided product and customer information.
 *
 * @param string $customerId       Seller ID, visible at the top-right corner of the admin page after login.
 * @param string $artnr            Unique product ID used for stock management.
 * @param float  $price            Price of the product including VAT.
 * @param string $title            Optional. Title of the product.
 * @param float  $vatAmount        Optional. VAT amount in fiat currency (SEK). Defaults to 25% of the price.
 * @param int    $maxSales         Optional. Maximum number of sales for this product.
 * @param string $customerKey      Optional. Customer key, either a 128-char randomized ASCII string or [customer id]-[32-char hex string].
 * @param float  $shippingStandard Optional. Shipping cost for standard shipping excluding VAT.
 * @param float  $shippingExpress  Optional. Shipping cost for express shipping excluding VAT.
 * 
 * @return string A script tag for a button based on the input parameters, or an empty string if required parameters are missing.
 */
function kwikk_generate_button($customerId, $artnr, $price, $customerKey, $btnText = '', $title = '', $vatAmount = '', $maxSales = '', $shippingStandard = '', $shippingExpress = ''){
	if(empty($customerId) || empty($artnr) || empty($price) || empty($customerKey)){
		return "";
	}

	$key = kwikk_generate_key($customerId, $artnr, $price, $customerKey, $vatAmount, $maxSales, $shippingStandard, $shippingExpress);
	
	$html =  "<script src='https://client.kwikk.se/kwikk-client.js' ";
	$html .= "data-seller='$customerId' ";
	$html .= "data-artnr='$artnr' ";
	$html .= "data-price='$price' ";
	$html .= "data-key='$key' ";
	if(!empty($title)) { $html .= "data-title='$title' "; }
	if(!empty($vatAmount)) { $html .= "data-vat='$vatAmount' "; }
	if(!empty($maxSales)) { $html .= "data-maxsales='$maxSales' "; }
	if(!empty($shippingStandard)) { $html .= "data-shippingstandard='$shippingStandard' "; }
	if(!empty($shippingExpress)) { $html .= "data-shippingexpress='$shippingExpress' "; }
	if(!empty($btnText)) { $html .= "data-btntext='$btnText' "; }
	$html .= "></script>";
	
	return $html;
}

This function outputs a script tag that, when included in your HTML, renders the Kwikk button dynamically with all specified attributes.

Example Usage:

// Generate a button on the page
function printBtn($orderNumber, $price){
	$artnr = "order-$orderNumber";
	$title = "Equipment from Company Inc. (order $orderNumber)";
	$price = $price;
	$btnText = 'Gå till betalning';
	
	$customerId = '(Your user ID)'; // Demo account, but with real payment services attached - contact hej@kwikk.se for refunds.
	$customerKey = '(Your user key)';
	$html = kwikk_generate_button($customerId, $artnr, $price, $customerKey, $btnText, $title);
	
	echo $html;
}
// printBtn(352, 10);

In your HTML, you simply call printBtn() where you want the button to appear, passing the order number and price as arguments.

Example implementation

Here's a full example that integrates the dynamic button into a webpage:

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Kwikk Exempel</title>
</head>
<style> body { font-family: sans-serif; } </style>
<body>
	<h1>Klicka nedan för att betala:</h1>
	<?php printBtn(352, 10); ?>
</body>
</html>

See the Pen Kwikk Exempel by David Forsberg (@davidanton1d) on CodePen.