FOR SELLERS WHO BUILD

The Velor Seller API

Manage your Velor store programmatically: create and edit listings, transfer a whole catalogue in batches, send photos, keep stock and prices in sync with your own systems, and set your shipping profile. Open to every approved seller. Ideal for cooperatives and workshops moving an existing catalogue onto Velor.

Base URL: https://velorglobalmarket.com/api/v1

Authentication

Every request carries an API key as a Bearer token:

Authorization: Bearer vlk_live_...

Create keys in your seller dashboard under API Keys. A key is shown once at creation and stored hashed, so save it somewhere safe; if a key is lost, revoke it and create a new one. Up to 5 active keys per store. You can only ever see and change your own listings; ownership is enforced on every route.

Step 1: your shipping profile

A listing cannot be created until your ship-from address is on file.

Required fields: name, street1, city, zip, country (a two-letter code such as BD, VN, DE). Optional: company, street2, state, phone, handlingFeeGBP (0-25, a flat buffer added to shipping quotes) and internationalFlatRateGBP (0-500, or null for FREE shipping with postage baked into your prices).

Listings

A create or edit body looks like this:

{
  "name": "Hand-woven jute basket",
  "category": "Home Craft & Decor",
  "price": 18.50,
  "description": "Woven by hand in Khulna from local jute...",
  "stock": 12,
  "images": ["https://your-site.com/photo1.jpg", "data:image/jpeg;base64,..."],
  "tags": ["jute", "basket", "fair trade"],
  "weightGrams": 400, "lengthCm": 30, "widthCm": 30, "heightCm": 20,
  "isHandmade": true,
  "makerStory": "Made by the artisans of...",
  "materials": "natural jute",
  "containsRegulatedMaterial": false,
  "rulesAccepted": true,
  "variants": [
    { "label": "Small", "stock": 6, "priceOverride": 14.50 },
    { "label": "Large", "stock": 6, "priceOverride": 22.00 }
  ]
}

Prices are in your own store currency. Between 3 and 8 images per listing, as https URLs or base64 data uploads; uploads are stored on Velor's image network automatically. Weight and dimensions are required on every listing (they drive customs declarations and delivery estimates). rulesAccepted: true confirms the listing complies with the Seller Rules and Product Compliance Policy, on every create and edit.

The same rules apply as in the dashboard, enforced on our side: no contact details in listings, no prohibited goods, variant prices within 3x of the base price, and the origin country always comes from your registered ship-from country. Listings go live instantly unless they involve a regulated material, in which case they are held for a human check first. Optional extras: videoUrl (YouTube or Vimeo), madeToOrder with leadTimeDays, and sizeGuide.

Transferring a whole catalogue

POST to /products/bulk with { "products": [ ...up to 25 listing bodies... ] }. There is no limit on the number of batches or total listings: a 500-item catalogue is 20 calls of 25. One bad listing never blocks the rest; the response tells you exactly which items succeeded and which failed, and why:

{
  "created": 23,
  "failed": 2,
  "results": [
    { "index": 0, "ok": true, "productId": "...", "status": "APPROVED" },
    { "index": 7, "ok": false, "error": "Please add at least 3 product images..." }
  ]
}

Fix the failures and resend only those items. For bulk imports, prefer https image URLs over base64 uploads: base64 photos inflate the request size quickly. If your photos only exist as files, send smaller batches, or create listings first and attach photos through the image endpoint below.

Photos on an existing listing

A listing holds 3 to 8 images; each variant can carry up to 6 of its own.

Shipping, taxes, duties and insurance

Velor is the marketplace, not the shipper. You arrange your own carriage and add tracking once an order ships. Every cost you carry is yours to price into what the buyer sees; Velor's only deductions are the flat commission and, on one legally required lane, UK VAT.

Shipping. Choose FREE shipping (postage baked into your item prices) or your own flat rate, both set on your shipping profile. Your shipping price is passed to you with the order, commission-free.

Taxes.Velor collects tax on exactly one lane, because UK law places it on the marketplace: goods shipped from outside the UK to a UK buyer in a consignment up to 135 pounds get 20 percent UK VAT added at checkout, collected and remitted by Velor. You do nothing for that lane. Everywhere else, Velor collects nothing; any import charges are the buyer's to settle at their border, unless you choose to ship duties-paid. Your own domestic tax obligations remain yours, as with any channel you sell through.

Duties. Declare contents honestly on the customs form and let the buyer pay any import charge on delivery (the default, stated plainly at checkout), or ship delivered-duty-paid through your carrier and bake that cost into your price.

Insurance. Velor sells none and requires none. If you want parcels covered, buy cover from your carrier and treat it like any other cost of carriage. Escrow already protects the buyer; insuring parcels protects you against loss in transit.

Keeping an external system in sync

Set your shipping profile once, then bulk-import in pages of 25 until your catalogue is across. Keep stock and prices current with PATCH (it is a full edit, so fetch the current listing first and send the whole body back with your changes). Retire items with DELETE; anything with real order history is delisted rather than destroyed, so past orders always keep their records.

Help

Stuck, or no developer to hand? Email hello@velorglobalmarket.com and tell us what format your product records are in; we will help you get them across.