Kowal B2B API — Complete REST Documentation

Contract version: V1 · Source of truth: Kowal_B2BApi/etc/webapi.xml · Audience: store administrators, implementation partners, and teams integrating ERP, PIM, WMS, or purchasing systems.

1. API purpose and boundaries

Kowal B2B API exposes B2B data and processes operating in Magento 2: companies, catalog and individual prices, quick purchasing, documents, trade credit limit, approvals, RFQ, and integration queues. It is a REST API for system integrations; it does not replace standard Magento endpoints for catalog, cart, checkout, and customer account.

The document describes only the endpoints currently exposed by the module. It does not promise operations not made available by the V1 contract, such as order creation via REST, price list CRUD, or website configuration editing.

2. Obtaining access and collaboration rules

2.1. Integration launch process

1. The integrator provides the store administrator with the integration goal, environment (test/production), source system, data scope, and list of required API areas.
2. The administrator creates or configures the Magento integration, assigns minimal ACL permissions, and securely provides: baseUrl, token, websiteId, companyId when applicable, currency, and test data.
3. The integrator runs the GET /V1/kowal-b2b/websites/:websiteId/config test, followed by functional tests in the test environment.
4. Before production, both parties agree on the synchronization schedule, maximum data size, retry, data owner, and error reporting method.
5. Tokens are stored only in a secrets vault; the administrator rotates or revokes them when the vendor, user, or integration scope changes.

2.2. Responsibilities

Do not use an administrator token in a client application or share one token across independent systems. Each integration should have its own token and only the required ACL.

2.3. Permissions

Magento verifies the Bearer token and ACL assigned to the administrative user or integration. B2B endpoints require one of the following permission groups:

The scope should result from the purpose of the integration. Example: a purchasing system usually needs products, prices, catalog_permissions, quick_order, and quotes; an ERP handling documents — documents and, if it owns synchronization, system_integrations.

3. Technical conventions

Address, headers, and parameters

The base address has the form https://b2b.example.com/rest/V1. All paths later in this document are provided from /V1; the full endpoint address is BASE_URL + path.

Authorization: Bearer Accept: application/jsonContent-Type: application/json

The API uses JSON. Names in URLs are camelCase (websiteId, companyId), and JSON fields correspond to Magento contract parameter names. :companyId, :quoteId, :sku, etc. are path parameters. In examples, ? indicates an optional parameter.

websiteId is required for sales channel-dependent operations. It must point to an existing website with B2B enabled. companyId points to a company that must have an active relationship with this website when the operation runs in its context. The API does not select a default website or company.

Request body and idempotency

Magento serializes the DTO object under the method parameter name: most write operations accept {'request': {...}}; company creation uses {'company': {...}}; company batch — {'companies': [...]}. Endpoints with simple arguments accept fields without a wrapper, e.g. {'websiteId': 1, 'currency': 'PLN', 'items': [...]}.

The Idempotency-Key header, max. 128 characters, is currently supported by POST /companies: retrying with the same key will return the previously created company. For an integration job, use the request.idempotencyKey field. Do not assume automatic idempotency of other write endpoints; retry them only after determining the operation status.

Responses and errors

Successful responses are Magento contract objects or arrays. Fields returned by objects may be extended in a compatible way; the integration should ignore unknown fields. A business error may contain:

{ 'code': 'b2b.company.not_assigned_to_website', 'message': 'B2B company is not assigned to website.', 'website_id': 1, 'trace_id': 'request-correlation-id', 'details': {'company_id': 10}, 'field_errors': []}

Do not log tokens, full personal data, or configuration secrets. A report to the store team should include time, method, path without secrets, HTTP status, trace_id, and anonymized payload.

4. Input data schemas

The schemas below are common to the reference endpoints. A field without ? is required by the contract; ? means an optional value. The metadata, config, configuration, and payload fields are JSON objects.

5. Endpoint reference

In the tables, ACL means the minimum Magento permission resource. Result defines the successful response type.

5.1. Websites and configuration

5.2. Companies and company users

5.3. Products, price, and catalog visibility

5.4. File import and export

5.5. Quick order and shopping lists

5.6. Documents and files

5.7. Trade credit limit and payment terms

5.8. Approval workflow

5.9. B2B order context

5.10. RFQ and commercial offers

5.11. Integration profiles and jobs

6. Example calls

export BASE_URL='https://b2b.example.com/rest/V1'export TOKEN='token-przekazany-przez-administratora'export WEBSITE_ID=1 COMPANY_ID=10 SKU='B2B-SKU-001' CURRENCY='PLN'# Test dostępu i konfiguracji kanałucurl -sS '$BASE_URL/kowal-b2b/websites/$WEBSITE_ID/config' \ -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/json'# Cena kontraktowa firmy dla konkretnej ilościcurl -sS '$BASE_URL/kowal-b2b/companies/$COMPANY_ID/products/$SKU/price?websiteId=$WEBSITE_ID&currency=$CURRENCY&qty=5' \ -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/json'# Walidacja koszyka po SKUcurl -sS -X POST '$BASE_URL/kowal-b2b/companies/$COMPANY_ID/quick-order/validate' \ -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \ --data '{'websiteId':1,'currency':'PLN','items':[{'sku':'B2B-SKU-001','qty':5}]}'# Utworzenie RFQcurl -sS -X POST '$BASE_URL/kowal-b2b/quotes' \ -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \ --data '{'request':{'websiteId':1,'companyId':10,'customerId':25,'title':'Dostawa kwartalna','currency':'PLN','externalId':'ERP-RFQ-2026-001'}}'

7. Recommended integration scenarios

Purchase by SKU

1. Read the website configuration and save the provided websiteId, companyId, and currency.
2. Use quick order for batch validation of SKU, quantity, visibility, and availability.
3. For accepted items, retrieve the price from price with the correct qty.
4. Create an RFQ, add items, and send them via submit if the purchase requires a quote.
5. Track RFQ status and history; after acceptance, follow the agreed Magento order process because V1 does not expose an order creation endpoint.

Documents and billing

1. Retrieve the company document list, optionally filtering by documentType.
2. For the selected document, retrieve metadata and the file list; the file path is not automatically a public URL — agree on the binary download method with the store administrator.
3. Read the limit status before the purchasing process; only an integration with credit_limits ACL can manage it.

Asynchronous operations

1. Save the integration profile and identifier mappings.
2. Publish a job with a business idempotencyKey and keep the jobId.
3. Read the job and logs/errors; call retry only after analyzing the error and removing its cause.

8. Pre-production acceptance list

• The token has only the required ACL and is not an administrator token used by the UI.
• The integrator correctly handles 401, 403, 404, 422 validation, 409 conflict, and timeouts.
• Each request in the B2B context provides the correct websiteId, and company data uses the correct companyId.
• Prices, visibility, and availability are checked before creating the purchasing process.
• Company creation uses Idempotency-Key; integration jobs have a stable idempotencyKey in the body.
• Logs do not contain tokens or sensitive data, and the support procedure provides trace_id.
• Tests were performed in a test environment on a company that has an active relationship with the B2B website.

9. Compatibility

The contract is versioned by /V1. Extending responses with new fields is compatible; the integrator should tolerate unknown fields. A change that removes a field, field meaning, or endpoint requires a new API version. If there is a discrepancy between the document and the running installation, the active webapi.xml contract of the given module version is binding.

Kowal B2B Suite Installation and Configuration

This manual is intended for the person who purchased Kowal B2B Suite and needs to launch it in an existing Magento Open Source installation. It guides you through two stages:

1. technical installation — performed by a developer or server administrator;
2. business configuration — performed in the Magento panel by the store administrator.

Before you begin, create a backup of the Magento database and files. We recommend performing the first launch in a test environment and only then deploying to production.

1. What you receive and what you need

Kowal B2B Suite is delivered as the Composer package kowal/metapackage-b2b-suite. It includes B2B modules and the frontend/Kowal/b2b theme.

Requirements

From Kowal, you will receive:

• private Composer repository address — referred to below as REPOSITORY_URL;
• user name or access identifier — USERNAME;
• access token — ACCESS_TOKEN;
• allowed package version range.

Do not store the token in the Git repository, tickets, or shell history shared with other people.

2. Technical installation

Run all commands in the root directory of the existing Magento installation, as a user with access to the files and to the bin/magento command.

2.1. Preparation

1. Make sure Magento works correctly before the change.
2. Save the deployment state and back up the database and the app/etc, pub/media, and var directories.
3. In production, enable maintenance mode for the update:

bin/magento maintenance:enable

2.2. Adding the private repository

Add the Kowal Composer repository and configure the access credentials you received.

You will receive Composer repository access credentials, the customer email address and license token, by email after purchase. They are also available in the customer panel after logging in at kowal.store. Replace TWOJ_EMAIL_KLIENTA with your account email address and TWOJ_TOKEN with the token you received. Run the commands in the Magento root directory.

composer config repositories.kowal composer https://repo.kowal.store
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

Composer usually stores credentials in the local auth.json; do not add this file to Git.

2.3. Package installation

Install the version provided with the license. For the current package line, an example command is:

composer require kowal/metapackage-b2b-suite:^0.2 --with-all-dependencies

After downloading dependencies, update the Magento schema and configuration:

bin/magento setup:upgrade
bin/magento cache:clean

In production mode, also run:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f pl_PL en_US
bin/magento cache:flush

Use only the locales that are active in the store. If the installation uses a different deployment process, add the above commands to its standard procedure.

2.4. Installation verification

bin/magento module:status | grep Kowal
bin/magento indexer:status

The admin panel should show the B2B menu and the Stores > Configuration > Kowal > B2B tab. If they are missing, check the setup:upgrade result, cache, and the ACL roles of the administrator user.

2.5. PDF file permissions

PDFs generated by B2B use mPDF and directories under var/, including var/tmp/kowal_b2b_mpdf and var/kowal_b2b_documents. The PHP process must be able to create and write to them. Missing permissions result in document or PDF generation errors.

After completing the production deployment, disable maintenance mode:

bin/magento maintenance:disable

3. Configuring the B2B store structure

3.1. Website and store view

The suite operates at the website scope, not globally. You can run B2C and B2B in the same Magento installation, but B2B should operate on a separate website or on a deliberately selected business sales website.

1. In Stores > Settings > All Stores, create or select the B2B website, its store, and store view.
2. Note the website_id — it is used by companies, prices, documents, API, and integrations.
3. In Content > Design > Configuration, assign the frontend/Kowal/b2b theme only to the B2B store view.
4. Verify that active currencies, taxes, shipping methods, and payment methods are configured for the same scope.

Do not assign the B2B theme to a B2C store view if you do not want to change its presentation layer. Installing the modules alone does not enable B2B logic for all websites.

3.2. Activating B2B

1. Open Stores > Configuration > Kowal > B2B.
2. In the scope switcher, select the correct Website.
3. In the General section, set Enable B2B to Yes.
4. During implementation, you can enable Debug Mode; disable it after testing.
5. In the Default Config scope, set the log retention period.
6. Save the configuration and clear cache.

After activation, all store views belonging to this website are treated as B2B. A company without an active relationship with this website will not gain access to it.

3.3. Seller data

Complete the selling company data in Stores > Configuration > General > Store Information: name, address, phone, and tax ID. They are used in documents and RFQ PDFs. Also complete the general sender email address in Sales Emails configuration and the email logo if it should appear in PDFs.

4. Configuring the first B2B customer

Use the following order for each company. It helps avoid a situation where the customer has an account but cannot see the offer or proceed through checkout.

4.1. Company, people, and addresses

1. Open B2B > Companies and create a company.
2. Enter the name, tax ID, external identifier if the company is synchronized with ERP, Active status, and assignment to the B2B website.
3. Add a company user or assign an existing Magento customer. Assign the correct role and activate the assignment.
4. In B2B > Company Addresses, add company addresses; mark the default billing and shipping address for the B2B website.
5. In B2B > Company Contacts, add an active primary contact with email and phone.

The billing address and primary contact are also used in RFQ PDFs. Missing data does not block the PDF, but the document will be less complete.

4.2. Company roles

Grant users only the permissions they need. A typical division is:

Test an account of each type, especially permission to place orders and approve them. Do not use one shared account for the entire company.

5. Offer, pricing, and checkout

5.1. Catalog and prices

1. Make sure Magento products are assigned to the B2B website, active, and have correct MSI data.
2. Configure price lists or contract prices for the company in B2B > Pricing (Price Lists, Price List Assignments, or Contract Prices).
3. Configure catalog visibility rules for the company according to the implemented permission model, then verify visibility on the customer account.
4. Test on the company account: SKU search, product visibility, and price for quantity 1 and for the quantity tier.

The B2B price depends on company, website, currency, and quantity. A product visible in B2C does not have to be available to a B2B customer.

5.2. Shipping and payment

1. Enable the required shipping and payment methods in the standard Magento configuration for the B2B store view.
2. In B2B > Checkout, add rules for available methods for the company/website if you want to restrict selection.
3. Run a cart test using the company default addresses.

If order creation from RFQ is expected to work automatically on the administrator side, the company must have unambiguous default addresses and active payment and shipping methods. Otherwise, the Suite will load the data into native Backend Order Create, where the administrator completes missing elements.

5.3. Limits and approvals

These features are optional, but they should be configured before enabling them for customers.

1. In B2B > Credit > Payment Terms, add payment terms.
2. In B2B > Credit > Credit Limits, assign a limit, currency, status, and payment term to the company.
3. In B2B > Approvals > Rules, create an amount threshold rule for the company and website.
4. In B2B > Approvals > Approvers, assign approvers.
5. Test the cart below and above the threshold and verify whether the approver decision changes the next step of the process.

6. Documents, PDF, and RFQ

6.1. Magento documents

In Stores > Configuration > Kowal > B2B > Documents, select the document source and decide which documents should be generated automatically: order confirmations, invoices, delivery documents, and credit memos. Also set the target document status.

In B2B > Documents > PDF Templates:

1. check the active template for each type and website;
2. preview it;
3. adjust HTML/CSS only if you have someone familiar with Magento templates and mPDF CSS;
4. generate a test invoice or confirmation and verify download from the company account.

6.2. RFQ and quote PDF

1. In B2B > Quotes > RFQ, create a test RFQ for an active company and user.
2. Add SKUs visible to the company, quantity, and quoted price.
3. Set the expiration date, send the quote to the customer, and generate the PDF.
4. Check the customer variant: seller/buyer data, items, price, total, and expiration date.
5. Check the administrator variant: additionally sales notes, comments, history, and internal item information.

The customer PDF must not contain salesperson notes or internal status history.

7. Quick orders, imports, and integrations

Quick orders

In B2B > Quick Order > Debug SKU, check the SKU,qty list for the company, website, and currency. Then create a shopping list and test its use by the customer on the storefront.

Import and export

In B2B > Import/Export, define a profile only after establishing the data source. Profile configuration is a JSON object and must contain file paths available on the Magento server. First run the import in test mode and analyze the job and logs.

API integrations

Before creating an integration token, define the data scope and synchronization owner. Use a separate Magento integration for each ERP, PIM, WMS, or middleware and grant only the required B2B ACL. The full list of endpoints, tokens, and security rules is available in the API documentation for integrators (request the current integration documentation from Kowal).

8. Acceptance checklist

Before production launch, confirm:

• ☐Kowal modules are active, cron works, and cache and indexes are correct.
• ☐B2B is enabled only for the correct website.
• ☐The B2B theme is assigned only to the B2B store view.
• ☐The test company has Active status, a user, role, contact, and default addresses.
• ☐The test product is active, assigned to the website, visible to the company, and has the correct B2B price.
• ☐The customer can log in, search for SKU, use quick order, and add a product to the cart.
• ☐Checkout shows only permitted shipping and payment methods.
• ☐The limit and approval rule work according to company policy if these features are used.
• ☐The document and RFQ PDF generate and are available only to the correct company.
• ☐RFQ can be sent, accepted, and passed to the order creation process.
• ☐Integrations have separate tokens and restricted ACL if they are used.

9. Most common issues

When contacting support, provide the Magento version, package version, reproduction steps, event time, safely anonymized logs, and any trace_id. Do not send tokens or passwords.

10. Package update

1. Review the release information provided by Kowal.
2. Perform the update first in a test environment.
3. Create a backup, run composer update kowal/metapackage-b2b-suite --with-all-dependencies, bin/magento setup:upgrade, and in production also DI compilation and static asset deployment.
4. Repeat the acceptance checklist, with special attention to prices, checkout, documents, and integrations.

Do not update the package by manually copying files to app/code; this causes Composer issues and makes future support more difficult.