Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/VisualGraphxLLC/API-HUB/llms.txt

Use this file to discover all available pages before exploring further.

Every wholesale data source in API-HUB is represented by a supplier record. Creating one takes less than five minutes if you have the supplier’s credentials ready. This guide covers the full flow from initial form entry through your first catalog import, using both the admin UI and the REST API.

​
Prerequisites

Before you start, have the following at hand:
  • The supplier’s protocol (promostandards or rest_hmac)
  • For PromoStandards suppliers: the supplier’s PS code (e.g. SANMAR, PCNA)
  • For REST suppliers: the base URL and API credentials (api_key / private_key)
  • The correct adapter class name (see Adapter overview)

​
Step-by-step guide

1

Open the Suppliers page

Navigate to Suppliers in the left sidebar. Click Add Supplier in the top-right corner. A form panel slides open.
2

Fill in the supplier fields

Complete each field:
FieldWhat to enter
NameDisplay name shown throughout the UI (e.g. SanMar)
SlugURL-safe unique key, auto-generated from the name
Protocolpromostandards for SOAP suppliers; rest_hmac for 4Over-style
PromoStandards codeThe supplier’s PS directory code (PS suppliers only)
Base URLRoot endpoint for REST suppliers; leave blank for PS suppliers
Adapter classRegistry key: PromoStandardsAdapter, SanMarAdapter, FourOverAdapter, or OPSAdapter
The slug must be unique across all suppliers. If you try to create a second record with the same slug, the API performs an upsert — updating credentials and setting is_active: true on the existing record instead of raising a conflict error.
3

Enter credentials

Expand the Auth config section. Credentials are stored as encrypted JSON (AES-128 via Fernet) and never appear in plaintext in the database.
{
  "id": "your-ps-account-id",
  "password": "your-ps-password"
}
4

Set protocol config (optional)

Use protocol_config for non-sensitive settings that the adapter reads at runtime. For example, to pin an explicit list of product IDs for a FILTERED_SAMPLE import:
{
  "explicit_list": ["PC61", "PC54", "K500"]
}
This field is stored as plain JSONB (not encrypted), so do not put credentials here.
5

Test the connection

Click Test connection before saving. The UI calls POST /api/suppliers/test with the form data you have entered.
POST /api/suppliers/test
Content-Type: application/json

{
  "protocol": "promostandards",
  "promostandards_code": "SANMAR"
}
What the test does:
  • For promostandards suppliers: looks up the PS code in the live PS directory (994+ registered companies). Returns ok: true if the code is found.
  • For rest_hmac suppliers: validates that auth_config.id and auth_config.password are present in the payload.
A successful response looks like:
{
  "ok": true,
  "message": "Supplier SANMAR found in PromoStandards directory"
}
A failure returns:
{
  "ok": false,
  "error": "Supplier XXXX not found in directory"
}
A successful test confirms the PS code exists in the directory. It does not validate your credentials against the supplier’s SOAP endpoint. Credential errors will surface on the first import job.
6

Create the supplier

Click Save. The UI posts to POST /api/suppliers. The server returns HTTP 201 with the new supplier record including its generated UUID.You can also create a supplier directly from the API:
POST /api/suppliers
Content-Type: application/json

{
  "name": "SanMar",
  "slug": "sanmar",
  "protocol": "promostandards",
  "promostandards_code": "SANMAR",
  "adapter_class": "SanMarAdapter",
  "auth_config": {
    "id": "your-ps-id",
    "password": "your-ps-password"
  },
  "is_active": true
}
Response (201 Created):
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "SanMar",
  "slug": "sanmar",
  "protocol": "promostandards",
  "promostandards_code": "SANMAR",
  "adapter_class": "SanMarAdapter",
  "is_active": true,
  "product_count": 0,
  "last_full_sync": null,
  "last_delta_sync": null,
  "created_at": "2026-05-07T12:00:00Z"
}
7

Activate the supplier

New suppliers are active by default when is_active: true is passed at creation. If you created the record as inactive, patch it:
PATCH /api/suppliers/sanmar
Content-Type: application/json

{
  "is_active": true
}
You can use either the UUID or the slug in the path. Only patchable fields are accepted: name, protocol, promostandards_code, base_url, adapter_class, auth_config, field_mappings, is_active, protocol_config.
8

Trigger a first import

Before scheduling a full sync, run a small test import to verify credentials and data shape. Use mode=first_n with limit=5 to fetch only the first five products:
POST /api/suppliers/3fa85f64-5717-4562-b3fc-2c963f66afa6/import
Content-Type: application/json

{
  "mode": "first_n",
  "limit": 5
}
The endpoint returns HTTP 202 Accepted immediately. The import runs in a background task.
{
  "sync_job_id": "c1a2b3d4-...",
  "supplier_id": "3fa85f64-...",
  "mode": "first_n",
  "accepted_at": "2026-05-07T12:01:00Z"
}
Track progress by polling the sync jobs list:
GET /api/suppliers/3fa85f64-5717-4562-b3fc-2c963f66afa6/sync-jobs
If the import fails with AdapterNotConfiguredError, the adapter_class field is null or not set. Patch the supplier with the correct adapter name before retrying.

​
Updating an existing supplier

Use PATCH /api/suppliers/{id_or_slug} to change any patchable field without affecting others. Partial updates are safe — only the keys you include are modified. 
PATCH /api/suppliers/sanmar
Content-Type: application/json

{
  "auth_config": {
    "id": "new-id",
    "password": "new-password"
  }
}

​
Deactivating and deleting

Set is_active: false to suspend all scheduled sync jobs without removing any data. The supplier record and its full catalog remain intact. Reactivate by patching is_active: true.
PATCH /api/suppliers/sanmar
Content-Type: application/json

{ "is_active": false }
DELETE /api/suppliers/{id_or_slug} removes the supplier record and permanently deletes all associated products, variants, images, categories, and sync job history. There is no soft-delete or undo.
DELETE /api/suppliers/sanmar
Response:
{ "deleted": true }

Build docs developers (and LLMs) love

Get started for freeTalk to us