1. Support
  2. For developers
  3. Add-ons
  4. Add-on creation

Add-on development

Guide to connecting your service with Upgates

REST API JSON Webhooks HTTPS (required)

Before you start developing

If you're unsure about anything, review the add-on's behavior with Upgates Technical Support (activation, normal operation, outages, later changes, and service termination). An early consultation helps prevent issues during approval. (Alternatively, you can use Discord)

Add-on architecture

Upgates communicates with your service's publicly accessible HTTPS endpoints. The add-on then works with a specific online store via REST API v2 and receives ongoing changes through webhooks.

01 Lifecycle

Upgates calls your service's install, open, uninstall and, where applicable, version endpoint.

02 Working with data

The add-on backend reads or modifies online store data using REST API v2.

03 Ongoing changes

The backend processes new and updated records primarily based on webhooks.

Base REST API URL

You receive the URL during the initial add-on initialization. Typical URL format:
https://NAZEV-ESHOPU.admin.ZNACKA-SERVERU.upgates.com/api/v2

Security requirement

All add-on endpoints must be publicly accessible over HTTPS. Store access credentials and the signature token only on the server. Never expose them to the user or send them to client-side code.

Marketplace settings

In the add-on detail, open the Add-on development.

ENDPOINTY

The Endpoints section consists of two parts: API settings and API access.

Important! For the add-on to work correctly (activation), both sections must be completed.

API settings

In the API settings section, enter publicly accessible HTTPS endpoints that Upgates will call during the individual stages of the add-on lifecycle.

INSTALL
Activation endpoint

Starts activation, account creation or matching, and initial add-on configuration.
Documentation

Required
OPEN
Open endpoint

Verifies the user and returns the URL of the add-on environment, which can be opened in the Upgates administration using an iframe.
Documentation

By solution
UNINSTALL
Uninstall endpoint

Notifies you that the add-on has been deactivated and its API access invalidated. Stop related tasks and terminate the integration.
Documentation

Required
VERSION
Version endpoint

Handles a customer's transition to a new version and applies any required changes to configuration, webhooks, or the user interface.
Documentation

When versioning
Signature token

signature_token is the add-on's secret identifier used to verify signatures of lifecycle requests. Do not store it in client-side code or publicly accessible logs.

API access

Request only the permissions the add-on actually uses. For each access, describe the purpose, expected frequency, and whether the call is triggered during installation, when data changes, or based on a webhook.

Important! Please provide an accurate and detailed description of the call frequency and the purpose for which you are requesting the API access.

Add-on activation

Add-on activation is the state when the client clicks the Activate button for the add-on in the Upgates administration.
Request body, Response, signature details and more can be found here.

  1. Verify signature (more here)
  2. Store access credentials
  3. Load /owner
  4. Create account / Match existing account
  5. Create webhooks and download / create the required data according to how the add-on works

Activation is initiated by a logged-in Upgates user, so it can be considered an authorized request. However, the implementation must safely handle repeated calls as well as activation of an already active add-on.

  • Each activation has its own separate API access (the URL remains the same).
  • The URL may change while the add-on is running (server identifier change). If you find that the URL returns a redirect when called, store the new URL and discard the old one.

After activating the add-on, create or link the customer account without unnecessary intermediate steps.

  • Get information about the online store operator using /owner.
  • Automatically create a new account or link an existing one.
  • After completion, take the user directly to the working environment.
  • Handle repeated activation requests safely and idempotently.

Do not require additional verification

Activation was performed by a logged-in Upgates user, so do not burden them with additional manual verification.

  • Do not require manual copying of integration tokens.
  • Do not send an additional confirmation or verification code by email.
  • Do not require users to re-enter data already provided by the API.
  • Do not expose API access credentials or the signature token to the customer.

Verification via Upgates OAuth

In development

Upgates OAuth allows you to securely verify a user without passing their login credentials to an external application. It is not yet possible to create your own OAuth application for a third-party service independently; support is planned as a future extension, and its completion will depend on specific use cases and developer interest. If you want to use OAuth in your add-on, contact us with a description of the intended integration.

Opening the add-on

If the add-on uses iframe, after verifying the request, the open endpoint returns the URL for the specific session. Make settings available directly in the Upgates administration whenever possible. If registration and account linking are fully automated and the add-on does not need its own interface, an iframe is not required. (More here)

Request body, Response, signature details and more can be found here.

Add-on deactivation

When the add-on is deactivated, Upgates sends a request to the add-on's uninstall endpoint. Your service must stop synchronization, invalidate stored access credentials, and securely close the connection to the online store.
More in our documentation here.

  1. Verify signature
  2. Stop synchronization
  3. Upgates deactivates
    • API access
    • Conversion codes (if you added them through the add-on API)

Deactivating a user on your side

If the user stops paying for your services / is overdue, or another situation occurs on your side that affects account deactivation, you must handle webhook deactivation.
When services are terminated / suspended on your side, you deactivate the webhooks. Upgates has no way to know this and will continue sending information to the webhooks, which will then fail. In these cases, use PUT to deactivate the webhooks, or for now delete them using DELETE. After reactivation, remember to activate / create them again.

Add-on versioning

Use a new version when the add-on's behavior, required permissions, or configuration changes. The customer's transition must be seamless and secure.
Learn more here.

Data synchronization

Pagination and batches

GET list requests should be paginated. The maximum number of items is usually 100. For POST and PUT supported endpoints can accept up to 100 items at once.

Languages and multiple domains

A single administration can contain multiple languages and domains. A product has one shared ID, but its content may differ by language version. During standard synchronization, load the object as a whole and handle the separation of language versions only in your own application. Filter by language only when you need to download specific languages, or when GET takes too long because of the number of products, variants, and language versions.

Products and variants

If a project has many products and GET takes too long or fails with an error, try reducing the number of products per page using current_page_items.

If a project has many variants and you either do not need them, or GET takes too long or fails with an error, try excluding variants using variants_yn and then download them using the separate endpoint /products/variants

Webhooks

After the initial data download, respond to changes using webhooks. Regularly downloading all orders or products increases load, consumes limits, and may be a reason for the add-on not being approved.

POST https://domenaprojektu.com/v2/webhooks JSON

{
    "name": "addonName",
    "url": "addonWebhookUrl",
    "event": "Orders.update"
}

Best practices

Follow the recommendations below to keep the add-on secure, reliable, and avoid unnecessary load on the API or connected online stores.

Automate

The goal is to provide clients with as much automation and convenience as possible when setting up the add-on. Avoid manual account creation, data entry, etc.

Multiple projects on one server

Distribute processing times throughout the day. Do not download data only at night or exactly at 00:00, etc. For example, we recommend staggering it as follows: online store ABC at 00:03, DEF at 00:07

Expect repeated requests

Activation, deactivation, and webhooks may arrive repeatedly or in an unexpected order. Design processing to be idempotent.

Use webhooks

Missing webhooks may result in the add-on not being approved, or in it being blocked if the issue occurs after approval.

Test your add-on

The key characteristics of add-ons are user-friendliness and optimized API usage. Avoid duplicate and unnecessary requests. Test the add-on properly before submitting it for approval (more here).

Detailed Rules and Best Practices

The primary goal of a verified add-on is to provide clients with the highest possible level of automation in the integration, without unnecessary clicks or form filling.

Rules for AI implementation

General

  • The add-on works through API communication. Basic Best Practices for using the API can be found here.
  • When working with the APIs of multiple online stores on one server, distribute the load throughout the day and do not download data only at night or at 00:00, etc.
    • For example, split the pool of online stores and add offsets by hours or other larger time intervals:
      • 2 online stores at 00:00
      • 2 online stores at 01:00
        etc.
  • Keep in mind that Upgates supports multiple languages and multiple domains.
    • What does this mean for you?
      You need to account for the fact that products, categories, articles, and other sections can exist in multiple languages across multiple domains, but within a single administration.
      For example, a product "T-shirt" can be available in CZ, SK, EN, can have its own domain for each language version, but will still exist in one administration under a single unique ID.
      Another product, "Jacket", may only be available in SK, but will still belong to the same administration as the "T-shirt" product.
    • If you handle multiple languages for products, categories, etc., download them as a whole (without limiting the URL to languages).
       Handle the separation into individual languages on your side. Downloading specific languages should be used, for example, when dealing with something related to a particular language version. For example, responding to the languages.create webhook when a new language version is created.
  • Use webhooks - Failure to comply may result in the add-on not being approved or later being blocked if detected by automated checks.
  • Add-on testing:
    • The main criterion when testing add-ons on your side should be user-friendliness. Before you submit the add-on to us for testing, please make sure you can use it as a regular customer would (the user account is created correctly, logging out and back into your environment works, etc.). This will make the overall add-on approval process easier.
    • The main goal of our review of your add-on will be to ensure the best possible API usage.
    • Do not use a "Synchronize" button. If you really need it for the add-on to work, protect it against repeated clicks and ensure the button cannot be pressed again while the original synchronization process is still running.
    • Link scheduled tasks to webhooks. There is no need to download all orders every day, especially when no new order has been created / no change has occurred.
    • More about this topic in our Help Center.

Add-on activation

  • When designing the add-on, you should account for the possibility that, even unintentionally, we may send multiple activation requests for an already active add-on or a deactivation request for an add-on that is currently inactive.
  • Activation (and any subsequent registration) can be treated as already verified (authorized), because it is always performed by a user in Upgates.

Account creation

  • To create or link an account, you can use /owner.
  • Fully automate account creation. Do not require the client to fill in a special form on your website. The client is verified on our side, so registration directly in your environment can be completed without unnecessary delays.
    • If /owner and other endpoints do not provide all the information required for registration, handle this using an iframe window.
    • Once you obtain the information from owner, create the customer's account so they can enter your environment immediately without unnecessary delays. Do not require the customer to additionally copy verification codes from emails, integration tokens, etc.
  • If your environment needs to indicate that the account is linked to the Upgates platform, this must happen during account creation. Do not require the customer to activate the integration separately on your side.
  • The user must not have access to the API access credentials, which are sent to you through the add-on. These communication credentials are for your use only, and the client must not be able to discover or reuse them.

Opening the add-on

  • It follows the rules for using the add-on iframe.
  • If matching an existing customer and registering a new one are both fully automated, there is no need to use an iframe.
  • (Recommended) Using an iframe, you can provide your application's settings to the client without requiring them to leave the Upgates administration, making the experience more convenient and faster.

Add-on operation

  • Synchronize / Update button
    If you need a button in your add-on to download current data (for example, orders), first remember the requirement to use webhooks. If the button really must be present, we recommend configuring it so that it cannot be used repeatedly within a few seconds. At a minimum, it should only become available after the previous download has completed, plus an optional interval.
    If changes were downloaded X seconds ago, the update button should not call the API again.
  • Webhooks (documentation here)
    • Users must not be able to bypass webhooks in your environment!
    • If you offer customers the option to run synchronization repeatedly, for example every few minutes, these time-based triggers must run on your side and check whether a webhook notification arrived during that interval. You must not call individual sections, for example every minute, to bypass webhooks.
  • Also consider non-paying clients
    If a client account reaches a state where you no longer process its data, you must deactivate the webhooks for the add-on integration. Otherwise, the project will unnecessarily log errors caused by invalid responses to webhook notifications.

Types of add-ons

In this section, we will try to describe the basic expected use of the API and how individual types of add-ons should work. If you cannot find your add-on described here, feel free to contact us and we can discuss the ideal behavior of your add-on together during an online meeting.

  • API access
    • Orders
      • GET - A one-time download back to a specific date is possible during activation (using ?page=), then always respond to webhooks (create, update).
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom -> Based on webhook
          • Webhooks: YES
      • PUT - Return order status changes and shipment tracking codes (custom number of repetitions - according to changes in orders on your side)
        • API access settings in Marketplace:
          • Frequency: Custom
          • Number of repetitions: Custom
      • Order statuses
        • GET - A one-time download is possible when the add-on is activated; afterwards, always respond to webhooks
          • API access settings in Marketplace:
            • Frequency: Only during installation and custom
            • Number of repetitions: Custom -> Based on webhook
            • Webhooks: YES
    • Products
      • GET - If you also work with products, a one-time download is possible during activation (using ?page=), then always respond to webhooks (create, update).
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom -> Based on webhook
          • Webhooks: YES
      • PUT - Watch product inventory management. Orders in Upgates automatically deduct products from stock when an order is placed. You should therefore not deduct products from stock again based on an incoming order in your system.
        • API access settings in Marketplace:
          • Frequency: Custom
          • Number of repetitions: Custom
    • Shipping and payment
      • GET - When the add-on is activated, shipping methods should be downloaded once and used to map carriers. Afterwards, always respond to webhooks.
        • API access settings in Marketplace:
          • Frequency: During installation and custom
          • Number of repetitions: Custom -> Based on webhook
          • Webhooks: YES
    • Owner (online store operator)
      • GET - When the add-on is activated, to match / create an account in your environment
        • API access settings in Marketplace:
          • Frequency: Only during installation
    • Webhooks
      • GET - Check before POST (during activation / transition to a new version)
        • API access settings in Marketplace:
          • Frequency: Custom / Only during installation and custom
          • Number of repetitions: Custom -> During add-on installation and transition to a new version
      • POST - Create webhooks for the most important sections: Orders, Products, Order statuses, Shipping and Payment
        • API access settings in Marketplace:
          • Frequency: Custom / Only during installation and custom
          • Number of repetitions: Custom -> During add-on installation and transition to a new version
  • Add-on information - Services
    • In the add-on detail for Marketplace, only services that you are able to provide to the customer as part of the add-on's operation should be mapped. Take into account carriers that the customer cannot configure in their administration (for example, downloading pickup points for a carrier that Upgates does not support, which means specific pickup points cannot be downloaded for it (FAN Courier)).

  • API access
    • Orders
      • GET - A one-time download back to a specific date is possible during activation (using ?page=), then always respond to webhooks (create, update).
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom -> Based on webhook
          • Webhooks: YES
      • PUT - Return order status changes and shipment tracking codes (custom number of repetitions - according to changes in orders on your side)
        • API access settings in Marketplace:
          • Frequency: Custom
          • Number of repetitions: Custom
      • Order statuses
        • GET - A one-time download is possible when the add-on is activated; afterwards, always respond to webhooks
          • API access settings in Marketplace:
            • Frequency: Only during installation and custom
            • Number of repetitions: Custom -> Based on webhook
            • Webhooks: YES
    • Products
      • GET - If you also work with products, a one-time download is possible during activation (using ?page=), then always respond to webhooks (create, update).
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom -> Based on webhook
          • Webhooks: YES
      • PUT - Watch product inventory management. Orders in Upgates automatically deduct products from stock when an order is placed. You should therefore not deduct products from stock again based on an incoming order in your system.
        • API access settings in Marketplace:
          • Frequency: Custom
          • Number of repetitions: Custom
      • Parameters and Related
        • GET - Download parameters from the product
          • API access settings in Marketplace:
            • Frequency: Only during installation and custom
            • Number of repetitions: Custom -> Based on webhook (Products.create, Products.update)
            • Webhooks: YES
    • Shipping and payment
      • GET - When the add-on is activated, shipping methods should be downloaded once and used to map carriers. Afterwards, always respond to webhooks.
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom -> Based on webhook
          • Webhooks: YES
    • Owner (online store operator)
      • GET - When the add-on is activated, to match / create an account in your environment
        • API access settings in Marketplace:
          • Frequency: Only during installation
    • Webhooks
      • GET - Check before POST (during activation / transition to a new version)
        • API access settings in Marketplace:
          • Frequency: Custom / Only during installation and custom
          • Number of repetitions: Custom -> During add-on installation and transition to a new version
      • POST - Create webhooks for the most important sections: Orders, Products, Order statuses, Shipping and Payment
        • API access settings in Marketplace:
          • Frequency: Custom / Only during installation and custom
          • Number of repetitions: Custom -> During add-on installation and transition to a new version

  • General
    • Mailing add-ons, must support two-way contact synchronization.
      • The most important synchronization point is whether the customer accepts the newsletter. If you store other customer data as well (name, phone, addresses), these data must also be synchronized back.
      • If a subscriber exists in SmartEmailing but not in Upgates, they should be created in Upgates to avoid unnecessary conflicts in the future.
  • API access
    • Orders
      • GET - A one-time download back to a specific date is possible during activation (using ?page=), then always respond to webhooks (create, update).
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom -> Based on webhook
          • Webhooks: YES
        • We also recommend including the option to integrate with product reviews.
    • Products
      • GET - If you also work with products, a one-time download during activation is recommended (using ?page=), then always respond to webhooks (create, update).
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom -> Based on webhook
          • Webhooks: YES
      • PUT - Watch product inventory management. Orders in Upgates automatically deduct products from stock when an order is placed. You should therefore not deduct products from stock again based on an incoming order in your system.
        • API access settings in Marketplace:
          • Frequency: Custom
          • Number of repetitions: Custom
    • Categories
      • GET - If you also work with categories, a one-time download during activation is recommended (using ?page=), then always respond to webhooks (create, update).
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom -> Based on webhook
          • Webhooks: YES
    • Customers
      • GET - One-time download during activation (using ?page=), then always respond to webhooks (create, update).
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom -> Based on webhook
          • Webhooks: YES
      • PUT - Synchronize the customer back based on a change in your system (unsubscribe from newsletter, name change, etc.)
        • API access settings in Marketplace:
          • Frequency: Custom
          • Number of repetitions: Custom
    • Conversion codes
      • GET - Check before POST (during activation / transition to a new version)
        • API access settings in Marketplace:
          • Frequency: Custom / Only during installation and custom
          • Number of repetitions: Custom -> During add-on installation and transition to a new version
      • POST - Create a conversion code
        • API access settings in Marketplace:
          • Frequency: Custom / Only during installation and custom
          • Number of repetitions: Custom -> During add-on installation and transition to a new version
      • DELETE - Delete a conversion code
        • API access settings in Marketplace:
          • Frequency: Custom / Only during installation and custom
          • Number of repetitions: Custom -> During add-on installation and transition to a new version
    • Discount coupons
      • GET - If you work with coupons, for example in email campaigns
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom / once a day (?active_yn / ?date_from + ?page)
      • POST - Create a discount coupon
        • API access settings in Marketplace:
          • Frequency: Custom
          • Number of repetitions: Custom -> When setting up name-day greetings, etc. in your system
      • DELETE - Delete a discount coupon
        • API access settings in Marketplace:
          • Frequency: Custom
          • Number of repetitions: Custom -> Coupons can be allowed to expire or deleted immediately
    • Languages
      • GET - When the add-on is activated, to correctly configure the customer profile in your system
        • API access settings in Marketplace:
          • Frequency: Only during installation and custom
          • Number of repetitions: Custom -> When responding to a webhook
          • Webhook: YES
    • Owner (online store operator)
      • GET - When the add-on is activated, to match / create an account in your environment
        • API access settings in Marketplace:
          • Frequency: Only during installation
    • Webhooks
      • GET - Check before POST (during activation / transition to a new version)
        • API access settings in Marketplace:
          • Frequency: Custom / Only during installation and custom
          • Number of repetitions: Custom -> During add-on installation and transition to a new version
      • POST - Create webhooks for the most important sections: Orders, Products, Languages, Shipping and Payment
        • API access settings in Marketplace:
          • Frequency: Custom / Only during installation and custom
          • Number of repetitions: Custom -> During add-on installation and transition to a new version

Add-ons built with AI or using AI as part of their operation are certainly a current trend.

However, these add-ons do not operate according to established rules (Best Practices), and even if AI is given clear commands and conditions, it is very likely that it will still devise its own method for achieving the requested goal.

To protect user data, we have prepared the following basic points that you need to address on your side:

  • The add-on should operate exclusively through the API.
  • The add-on (typically implemented through browser extensions) may work with page content by, for example, focusing or otherwise highlighting a section the customer is looking for, but it should not "physically" interact with the administration page to change data or switch settings on the customer's behalf.
  • Before the initial consultation and before submitting the add-on for approval, you must clearly document for both us and clients what the add-on is capable of doing (what it can access and what it can provide: translations, search, order status changes, etc.)
    • In the future, whenever a new feature is added, you will need to contact our technical support and inform us. This applies even when no API endpoints are added or changed.
    • You must record this change in the Add-on information and submit it to us for approval before the feature is deployed and made available to regular clients.
  • Ensure thoroughly optimized API calls
    • Paginate list requests and do not allow all products to be downloaded arbitrarily.
    • Do not allow Best Practices to be bypassed by customer instructions.
    • On activation, the add-on should download the product list, store it, and then work with webhooks. The add-on must not call all products after every customer request (for example, via chat).
    • Protect against broad customer requests (for example: "Add the manufacturer to the name of every product"). The add-on should not suddenly call 100,000 products as separate requests; instead, it should summarize the operation and proceed according to the API rules.
    • The add-on should cache the current chat and recent chats for at least 1 hour. This prevents a scenario where the add-on downloads all products, categories, etc. in one chat, processes the client's requests, the client closes the window, remembers a minute later that they need another change, reopens the window, and all products, categories, etc. are downloaded again.
    • If API communication is still in progress (data is still being downloaded or sent to Upgates), the add-on should not accept additional commands and create an endless queue of tasks.
  • Customer data protection
    • Before every action, the add-on should validate the customer's request and then clearly state what it will do and how many products (articles, categories, parameters, etc.) it will affect.
    • After this validation and warning, the add-on should always ask whether it should actually perform the action. It must not happen that a client enters a general request such as "change DPD shipping to PPL" and, instead of changing the shipping method name in the shipping methods list, the add-on starts changing all orders going back 10 years because they use DPD shipping.
    • The add-on should be responsible for backing up the data it edits and deletes and provide a way to restore the state from before the changes were made.
    • The add-on should take into account all related functions provided by Upgates. For example, if it starts changing the statuses of all orders, even by mistake, emails and SMS messages may be sent to customers. Bulk actions should therefore not be performed automatically, but only after the client has been fully informed and has explicitly confirmed them. Such a decision must also be logged on your side.
  • The add-on should be compatible with current versions and the most widely used systems and browsers
  • The add-on must ensure that the customer is informed and that their consent is stored when data (their own and their customers') is shared not only with your company but also with third-party services (OpenAI, etc.) that work with and process the data.
  • When the add-on is launched, the first step must include an iframe in which the client acknowledges a notice that the add-on is not affiliated with Upgates, is fully owned by your company (specify who has access to the data), and that Upgates is not responsible for data changes made by the add-on in the online store, nor is Upgates required to restore the data free of charge. (This consent must also be logged.)
On this page

Další zdroje informací

Facebook Forum

Výměna zkušeností, rady a tipy mezi provozovateli e-shopů na systému Upgates.

Přejít do fóra

Akademie

Získejte znalosti od našich specialistů na marketing, obchod, právo a podnikání.

Přejít do akademie

Novinky z Blogu

Co nového jsme pro vás připravili nebo chystáme najdete na blogu.

Přejít do blogu

Nepodařilo se Vám najít tu správnou odpověď?

Kontaktujte naši technickou podporu, která je tu pro vás od pondělí do pátku 8:00 až 16:00 hod.

Zákaznická podpora