Prerequisites

Before you can install or manage a UI extension using the public APIs, you need a few key pieces of information and the right access rights.

Public API reference

All operations described below are based on the official OneStock public APIs:

• Create an extension: https://developers.onestock-retail.com/paths/extensions/post

• Edit an extension: https://developers.onestock-retail.com/paths/extensions-id/patch

• Query extensions: https://developers.onestock-retail.com/paths/extensions-query/post

• Get a single extension: https://developers.onestock-retail.com/paths/extensions-id/get

• Delete an extension: https://developers.onestock-retail.com/paths/extensions-id/delete

• Rotate hash keys: https://developers.onestock-retail.com/paths/extensions-id--hash_keys/post

Always refer to these links for the authoritative list of fields, data types and response formats.

Required information

• site_id: identifies which site (tenant) the extension belongs to. You usually get this from your project or onboarding documentation.

• Authentication: you need a user or client with the appropriate permissions (for example client admin or configuration manager) to call the public APIs.

• Base URL: the base URL of the public API for your environment (for example sandbox, pre‑production, production). You will prepend this to the paths listed above.

Concepts to understand

• UI extension: a small piece of UI that is injected into a specific screen or area of the back office (for example an order page or a shipment page).

• Injection point: the location where the extension appears. It is defined mainly by:

  • anchor (for example bo.page),

  • path (the internal route),

  • slug (a short identifier),

  • roles,

  • rank,

  • and any icons or labels.

• test_url vs production url: you can configure a test URL to validate the extension in a non‑production context, and a production URL for live use. This allows you to test changes safely while keeping the live experience stable.

1. Install a new UI extension – POST /extensions

Reference: https://developers.onestock-retail.com/paths/extensions/post

Installing a UI extension means creating a new extension entry via the public API for a given site_id. You define where it will appear in the back office and which users will see it.

Business view

When you install a new extension, you will typically provide:

• Identity

  • name: a readable name so the extension is easy to identify in tools and logs.

  • description: a short explanation of what the extension does.

  • site_id: links the extension to the correct tenant.

• Where it is injected

  • anchor: the main area of the back office (for example bo.page).

  • path: Your extension might have multiple injection points. The path is the internal route to reach a specific extension internal route that narrows down the exact page or section (for example /orders/{orderId}).

  • slug: a short, unique identifier for the extension within that context. It will be used to translate some contents that are displayed by our UI. See UI Extensibility - How to develop UI Extensions for more details

• Front‑end URLs

  • test_url: URL used for testing and validation.

  • url: production URL used for live traffic.

• Permissions and visibility

  • disabled_for_roles and enabled_for_roles: which roles can see and use the extension.

  • rank: ordering when several extensions are displayed in the same area.

• Visual elements

  • icon : optional visual elements to make the extension clearer for users, value to be passed by API as a base64 data.

Refer to the API reference for the full list of supported fields and their types.

Example

Create a extension displaying a new page in the Backoffice, a bulk action in the orders page, and an action on the order detail page

POST /extensions

After this installation our Backoffice will display:

• A menu entry “Extension” on the backoffice menu.

  • Clicking on this menu will display the content of your extension at the url https://my-extension-url.com/page

• A CTA “Extension” when selecting one or more orders in the Orders page.

  • Clicking on this menu will display a popup with the content of your extension at the url https://my-extension-url.com/orders

• A “Extension” option in the burger dropdown of an order detail

  • Clicking on this menu will display a popup with the content of your extension at the url https://my-extension-url.com/order

2. Edit an extension – PATCH /extensions/{id}

Reference: https://developers.onestock-retail.com/paths/extensions-id/patch

Editing an extension lets you adjust how it behaves or where it appears without recreating it. You typically use this endpoint once the extension is installed and you need to:

• change the URL of the front‑end application,

• refine the injection point (anchor, path, slug, rank),

• restrict or open access to new roles,

• or temporarily disable the extension.

You need the id of the extension, which you can obtain from:

• the response to POST /extensions, or

• a search via POST /extensions/query.

Business view

With PATCH /extensions/{id}, you can:

• Change visibility

  • Update enabled_for_roles or disabled_for_roles to add or remove which back‑office roles can see the extension.

• Add a new UI extension in your existing project

  • Add a new injection point to boost the efficiency of all your team members : headquarters, customer service, financial…

• Manage test vs production rollout

  • Point test_url to a new version of your UI for QA or feature testing.

  • Update the production url when promoting a tested version to all users.

You usually perform these changes as part of regular lifecycle management: feature rollout, UX re‑organisation, or access control reviews.

3. Retrieve and list UI extensions

You can use the public APIs to check which extensions exist for a site, or to inspect the configuration of a specific extension.

3.1 List by criteria – POST /extensions/query

Reference: https://developers.onestock-retail.com/paths/extensions-query/post

Use this when you want to:

• list all extensions for a given site_id,

• search by criteria (for example slug or anchor),

• or retrieve several extensions in one call.

Typical usage:

• Provide site_id and any filters supported by the public API.

• Use pagination or sorting options if available (see the API reference).

3.2 Retrieve a single extension – GET /extensions/{id}

Reference: https://developers.onestock-retail.com/paths/extensions-id/get

Use this endpoint when you already know the internal id of the extension, for example:

• right after creating it with POST /extensions,

• or from the results of POST /extensions/query.

4. Delete an extension – DELETE /extensions/{id}

Reference: https://developers.onestock-retail.com/paths/extensions-id/delete

Deleting an extension removes it entirely so it no longer appears in the back office. Use this when an extension is obsolete, replaced, or no longer needed.

5. Hash key rotation and update – POST /extensions/{id}/hash_keys

Reference: https://developers.onestock-retail.com/paths/extensions-id--hash_keys/post

Hash keys are used to secure communication between the OneStock platform and your UI extension’s front end. The public API allows you to regenerate or rotate these keys when needed.

When to rotate or update hash keys

Typical situations include:

• Security review or policy

  • Your security team requires regular key rotation for compliance.

• Incident or suspected exposure

  • You suspect a key has been shared outside the intended team or may have been compromised.

• Change of vendor or hosting

  • The extension is moved to a new hosting provider or handed over to a new team, and you want to ensure only the right party can validate traffic.

Business impact and precautions

• Coordinated change

  • Coordinate with the team maintaining the extension front end so they update their configuration with the new hash key at the same time.

• Short maintenance window

  • Plan a small window (ideally during low activity) because requests can fail if the extension still uses the old key after rotation.

• Documentation and support

  • Document which extensions had their keys rotated, when, and by whom.

  • Inform support teams so they can quickly correlate any incidents with the rotation.

6. Production vs test URLs and injection points

The public APIs expose the same logical concepts you configure from the back office: test/production URLs and injection points.

Using test_url vs production url

• test_url

  • Use it for validation and experimentation (for example QA, feature branches).

  • Can be restricted to a limited set of roles or a test environment.

• Production url

  • Use it for live traffic once the extension has been validated.

  • Should point to a stable and monitored deployment.

• Both together

  • You can keep both configured:

    • testers or specific environments use test_url,

    • general users in production use url.

Check the POST /extensions and update operation in the public docs for the exact field names and any environment‑specific options.

Understanding injection points

To ensure the extension appears exactly where you want it, configure the following fields as exposed by the public APIs:

• anchor

  • Selects the general area of the back office, such as a main page zone (bo.page).

  • Serves as the starting point of the injection.

• path

  • Refines the location to a specific route (for example /orders/{orderId} or /shipments/{shipmentId}).

• slug

  • A friendly identifier that distinguishes this extension from others at the same anchor and path.

  • Helpful for maintenance, troubleshooting and searching via POST /extensions/query.

• roles

  • Controls which back‑office roles can see the extension.

  • Use this to restrict advanced tools to administrators or open customer support tools to agents.

• rank

  • Determines the order in which several extensions appear when they share the same area.

  • Use it to keep the most important tools visible or grouped together.

• Icons and labels

  • Influence how the extension is presented in the UI (menus, side panels, buttons).

  • Choose clear names and icons so users can quickly recognise the purpose.

7. Troubleshooting

If a UI extension does not appear or does not behave as expected, you can use both the back‑office UI and the public APIs to investigate.

Common checks

• Extension not visible

  • Check that your connected user matches the disabled_for_roles and enabled_for_roles

  • Use POST /extensions/query to confirm the current configuration of your extension.

• Wrong page or position

  • Confirm that anchor, path, and slug match the expected page and route.

  • If multiple extensions are present in the same area, adjust rank.

  • You can:

    • list them via POST /extensions/query,

    • inspect an individual configuration via GET /extensions/{id}.

• Test vs production confusion

  • Make sure you are on the right environment (sandbox vs production).

  • Confirm that test_url and url are configured correctly for that environment using the public APIs.

  • If needed, update them via the appropriate update endpoint.

• Errors after rotating hash keys

  • Confirm that the extension front end has been updated with the latest hash keys returned by POST /extensions/{id}/hash_keys.

  • If necessary, regenerate the keys and repeat the update in a coordinated window.

When to contact support

For persistent issues:

1. Collect:

   • the extension id,

   • the site_id,

   • the environment (staging, production),

   • and a short description of the scenario (page, user role, expected vs actual behaviour).

2. Share this information with your technical contact or support team, along with:

   • recent API calls you made (POST /extensions, POST /extensions/query, etc.),

   • and any relevant error responses from the public APIs.

This will help them quickly diagnose configuration or integration issues using the same public API surface you are using.