Your systems.
One connected stock record.

Start with a connection you can verify

The API is designed for your server to call VapeTax using a key created by your account owner. The same account boundaries and inventory protections apply to API operations and the app.

API base URL

https://api.vapetax.co.uk/integrations/v1

Use the API origin, not the website address. Your technical contact supplies the origin for an authorised sandbox. An example local origin is http://localhost:4016; localhost means the computer running your connector.

# Set VAPETAX_API_URL and VAPETAX_API_KEY in private server configuration.
# VAPETAX_API_URL contains the origin, without /integrations/v1.
curl "$VAPETAX_API_URL/integrations/v1/capabilities" \
  -H "Authorization: Bearer $VAPETAX_API_KEY" \
  -H "Accept: application/json"

Authentication & scopes

Send your integration key in the Authorization header on every request. Keep it in your server’s secret configuration. Never put it in a URL, browser storage, client-side code, source control, screenshots or a shared Postman export.

Authorization: Bearer <your integration API key>
Accept: application/json
Content-Type: application/json

Keys are shown once. They expire within 90 days and can be revoked immediately. Each integration allows two active keys so you can create a replacement, update your connector, verify it and revoke the old key without interrupting service.

Read and write scopes are separate. A write scope does not automatically grant a read scope. The endpoint reference states the exact access needed; GET /capabilities returns the effective scopes of the key you are using.

The account owner creates keys and reviews inventory using their browser session. Integration keys cannot become an owner, approve opening holdings, manage credentials, access platform administration or restore the workspace. Owner-only endpoints are separately labelled in the reference.

Products, SKUs & packaging barcodes

Begin by synchronising the product catalogue. A product has a stable VapeTax ID, your external product ID, a name, SKU, optional liquid volume and packaging barcodes. Imported products appear in Products & Barcodes and the Production product picker.

Import a new product

Save the exact JSON payload and a stable batch key in your connector before sending. Send 1–100 products per import, with up to 20 barcodes per product.

POST /integrations/v1/products/import
Idempotency-Key: example-catalogue-001
Content-Type: application/json

{
  "products": [
    {
      "externalProductId": "EXAMPLE-BLUE-10ML",
      "name": "Example Blueberry 10ml",
      "sku": "BLUE-10ML",
      "volumeMl": 10,
      "barcodes": [
        {
          "code": "EXAMPLE-BLUE-ITEM",
          "level": "ITEM",
          "unitsPerPack": 1
        },
        {
          "code": "EXAMPLE-BLUE-PACK5",
          "level": "PACK",
          "containsCode": "EXAMPLE-BLUE-ITEM",
          "containsQty": 5
        }
      ]
    }
  ]
}

A first accepted import returns HTTP 201; an identical retry returns HTTP 200 and the original import ID. A changed payload using an accepted key returns a conflict. The import operation does not silently overwrite or adopt an existing catalogue product; resolve mapping conflicts with the account owner.

Three identifiers with different jobs

Never multiply a packaging barcode’s nominal pack size to establish a duty quantity. Warehouse actions use the actual recorded units. A unique warehouse-readable aggregation alias must identify the physical container; a SKU barcode cannot serve as that alias.

Find codes by batch or production number

Use inventory queries to connect the commercial product to the individual goods. Query by SKU, packaging barcode, batch, production number or verified warehouse. Follow the returned cursor to read every page.

GET /inventory/scans reads known scanned units, including goods that have not been reconciled. GET /inventory/units reads approved holdings with warehouse and reservation context. A scan record alone is not proof of approved inventory or release eligibility. Native loose stamps may have no recorded product, batch or expiry; those values remain unknown.

GET /integrations/v1/inventory/units?sku=BLUE-10ML
GET /integrations/v1/inventory/units?barcode=EXAMPLE-BLUE-ITEM
GET /integrations/v1/inventory/units?batch=EXAMPLE-BATCH-001
GET /integrations/v1/inventory/units?productionNumber=PROD-EXAMPLE
GET /integrations/v1/inventory/units?warehouseId=<verified-warehouse-id>

URL-encode each filter value. Codes and stable external identities are case-sensitive. A product may occur in many batches; use the batch or production reference when you need one manufacturing run.

Read aggregation records and their contents with the inventory aggregation endpoints. Quantity-only legacy cases must be reconciled into complete identities before they can enter the verified release workflow.

Read an individual unit’s traceability

The following shows selected fields from an illustrative units response. Null means the value has not been recorded. Reservation references are disclosed only to the integration that owns them.

{
  "id": "example-unit-id",
  "stampCode": "UKVDSDRY/FAKEEXAMPLE01",
  "product": {
    "id": "example-product-id",
    "name": "Example Blueberry 10ml",
    "sku": "BLUE-10ML",
    "liquidMlPerRetailUnit": "10.000"
  },
  "batch": "EXAMPLE-BATCH-001",
  "expiryDate": "2027-10-15",
  "productionNumber": "PROD-EXAMPLE",
  "warehouseId": "example-warehouse-id",
  "treatment": "NEW_RELEASE",
  "availability": "AVAILABLE",
  "orderAllocationId": null,
  "externalOrderId": null,
  "aggregation": null
}

Read & write operational records

The versioned integration API exposes operational workflows with explicit scopes. Use the endpoint reference for the exact method, path and fields. Writes preserve the same source, lifecycle, stock and evidence checks as the app.

Access to a documented operation is still subject to account status, plan limits, the key’s scope and server readiness. A protected-history conflict means the record needs reconciliation and an authorised correction, not a different endpoint.

Machine-created stamp receipts begin in Product duty suspended. Use the dedicated lifecycle and release operations for later actions; a receipt status cannot bypass release accounting.

Reserve units, then move or despatch them

Allocate an order

An allocation reserves specific retail units for an external order. It records an exact selection of stamp codes or aggregation contents, rather than only a planned quantity. Read the reservation to see its current state; cancel it through the cancellation endpoint when those goods are no longer required.

GET  /integrations/v1/order-allocations
POST /integrations/v1/order-allocations
GET  /integrations/v1/order-allocations/{id}
POST /integrations/v1/order-allocations/{id}/cancel

POST /integrations/v1/order-allocations
Idempotency-Key: example-allocation-001

{
  "externalAllocationId": "EXAMPLE-ALLOCATION-001",
  "externalOrderId": "EXAMPLE-ORDER-001",
  "warehouseId": "example-warehouse-id",
  "stampCodes": [
    "UKVDSDRY/FAKEEXAMPLE01"
  ],
  "aggregationCodes": []
}

Allocation states are RESERVED, PARTIALLY_RELEASED, RELEASED and CANCELLED. The receipt reports total, reserved, released and cancelled units. New acceptance returns HTTP 201; an identical replay returns HTTP 200. A changed request under the same key or external allocation identity returns HTTP 409.

Two orders cannot reserve the same available unit at once. A release must respect the reservation’s order and integration ownership. Use a different stable despatch ID for each partial delivery of the same order. Cancelling a reservation does not reverse a completed release or its duty.

Transfer units between warehouses

A transfer moves selected verified goods between approved premises in the same permitted duty-suspended state. It does not release them into free circulation, post VPD or claim SICPA confirmation. The service checks the exact units and current holding before recording the movement.

POST /integrations/v1/inventory/transfers

{
  "externalTransferId": "EXAMPLE-TRANSFER-001",
  "fromWarehouseId": "example-source-warehouse-id",
  "toWarehouseId": "example-destination-warehouse-id",
  "movementType": "DUTY_SUSPENDED_TRANSFER",
  "occurredAt": "2026-10-15T10:00:00+01:00",
  "custodyEvidence": "FICTIONAL — replace with verified custody evidence",
  "authorityEvidence": "FICTIONAL — replace with verified movement authority",
  "stampCodes": [
    "UKVDSDRY/FAKEEXAMPLE01"
  ],
  "aggregationCodes": []
}

Both warehouses must be verified and classified as DUTY_SUSPENDED by the owner. Cancel any reservation before transferring its units. Send a persisted Idempotency-Key: a new transfer returns HTTP 201 and an identical replay returns HTTP 200. The same key or external transfer identity with different content returns HTTP 409.

For a move into free circulation, use the release workflow below. Do not label it as a warehouse transfer to avoid accounting. Transfers involving a change of tax treatment require the reviewed workflow for that treatment.

A despatch, its duty record & its notification

When goods actually enter free circulation, VapeTax records the local release and mandatory VPD accounting together in one transaction. If an acceptance check fails, neither a partial release nor a partial duty posting is left behind. Provider delivery happens separately.

1. Reconcile the holding

   The actual account owner approves the complete opening manifest, verified premises, source quantities, total liquid per retail unit, activation and historical duty evidence.

2. Preview the exact selection

   POST /release-validations checks eligibility and previews quantities and duty. Validation is advisory; it does not reserve goods or record a release.

3. Persist and submit the despatch

   POST /releases uses a stable externalDespatchId, your persisted Idempotency-Key, actual releasedAt time, warehouse, customer, operator and exact codes. Acceptance rechecks everything under the account lock.

4. Store the receipt and follow status

   HTTP 202 records local acceptance. Keep the returned release ID and poll the status URL. After a lost response, recover by externalDespatchId and retry the original request unchanged.

NEW_RELEASE and RELEASE_FROM_BOND follow their verified accounting treatment; ALREADY_ACCOUNTED goods link to prior duty without charging again. The server resolves actual leaf units and liquid volume from the approved holding, never from a nominal case size or a client-supplied total.

A provider outage does not move the tax point. The local records and durable notification remain available for recovery. SIMULATED, LOCAL_ONLY, QUEUED and PROCESSING are not live SICPA confirmations. A SANDBOX confirmation proves only that sandbox event’s result. UNKNOWN requires investigation of the original event UUID; do not blindly resend it.

Accepted release evidence is retained. Corrections need a reviewed, authorised process; deleting ledger records or restoring an older workspace is not a reversal mechanism.

Build reliable retries & recovery

Keep business identities stable

Persist the payload, business identity and Idempotency-Key before the first request. On a network timeout or retryable server failure, resend the identical request with the same key. Do not generate another despatch identity to resolve uncertainty. Key rotation does not change the integration’s business identity.

Only endpoints that document idempotency provide that guarantee. Do not automatically replay ordinary record-creation or stock-changing operations after a lost response; read the resulting state and reconcile first.

Pagination and limits

For cursor-paginated endpoints, start without cursor and pass the returned nextCursor on the next request. Stop when nextCursor is null. Keep the same filters across pages; do not interpret one page as the whole inventory.

GET /integrations/v1/products
GET /integrations/v1/products?cursor=<URL-encoded-nextCursor>

Integration JSON bodies are limited to 1 MiB. The baseline throttle is 60 requests per key per minute and 300 per account per minute across integrations. Respect Retry-After on HTTP 429 and use bounded backoff with jitter. Read capabilities and each operation’s schema for batch, hierarchy and quantity limits.

The isolated release pilot currently accepts at most seven days of backdating and five minutes of future clock skew. Its rate and rounding policy is a review guard, not an agreement to enable live use. Preserve the actual timestamp and timezone offset in your saved request.

Handle errors deliberately

Prepare your Sage / OrderWise sandbox

Your connector calls the standard VapeTax API. This does not install a native Sage or OrderWise plugin, remotely control scanners or automatically print aggregation aliases. Your technical contact confirms the installed versions, supported hooks and ownership of the adapter.

• Confirm installed Sage 200 Professional and OrderWise versions, integration hooks and the adapter’s technical owner.
• Provide a redacted real product and despatch payload, total liquid per retail unit, scanner symbologies and unique aggregation alias / printing requirements.
• Obtain authorised sandbox Economic Operator, location and machine identifiers, credentials and independently activated test stamps.
• Reconcile complete opening holdings, ownership, custody, source quantities and historical duty with the account owner.
• Prove partial despatch, competing reservations, duplicate requests, outages, recovery, polling and correction handling in the authorised sandbox.
• Agree operational load, rate changes, rounding, backdating, retention and a recovery rehearsal before a separate live review.

Endpoint reference

Search by task, path, scope or field name. Expand an endpoint to see its parameters, nested JSON fields and response schemas. This reference is generated from the downloadable OpenAPI specification.

Paths below include /integrations/v1 for machine operations. Owner management paths use a browser session and are visible through the Access filter. This reference never asks you to paste a secret or sends API requests.

Take the reference into your tools

Import the OpenAPI specification into your API tooling or use the Postman collection. The .NET examples show durable request identities, bounded retries and separate release/accounting/provider outcomes.

Example codes, customer names, references and evidence are fictional. Replace them with authorised test fixtures and actual evidence; examples do not establish stock, activation or paid duty.