Vendor

Vendor (seller) resource for the GunSpec SDK. Wraps /v1/vendor/* and the outbound click route. A seller holds an Enterprise plan and names one of their ordinary keys in Profile > Seller; that mapping is the whole vendor scope, so there is no separate credential to configure here. A key no shop names answers 403 KEY_NOT_LINKED_TO_SHOP. A feed reads before it writes: shops() tells a script which ids it can act for, listOffers() returns what the API holds, and updateOffer() changes one field without resending the rest.

Authentifizierung erforderlichEnterprise

client.vendor.shops()

The shops this key may act for. A script learns its shop ids here.

shops(): Promise<APIResponse<VendorShop[]>>

GET/v1/vendor/shops

Enterprise

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

application/json

object[]
The response payload.
string
Slug of the shop. This is the value to send as ?vendor=.
string
Display name, as the maker writes it.
string | null
Official website, where one is known.
string | null
ISO 4217 code the price is in, e.g. AUD. Prices are integer minor units; format with Intl.NumberFormat at render rather than dividing first.
boolean
Whether staff have approved the shop. An unapproved shop accepts writes but shows nothing publicly.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Alle Anfragelimits

Mindeststufe: Enterprise
Monatskontingent: 1,000,000/mo
Anfragerate: 300/min
Tageslimit: 50,000

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.vendor.shops();6console.log(data);

1{2  "success": true,3  "data": [4    {5      "id": "ridgeline-optics",6      "name": "Ridgeline Optics",7      "website": "https://ridgeline.example",8      "currency": "AUD",9      "approved": true10    }11  ]12}

Authentifizierung erforderlichEnterprise

client.vendor.listOffers()

Your listings as the API holds them, stockQty and click counts included.

listOffers(params?: ListVendorOffersParams): Promise<PaginatedResponse<VendorOffer>>

GET/v1/vendor/offers

Enterprise

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

string
Which of your shops to act for. Required only when one key is named by more than one shop; GET /v1/vendor/shops lists them
Max. Länge
64
Beispiel
string
Only parts or only firearms
Akzeptiert
Max. Länge
40
string
Only drafts or only published rows
Akzeptiert
string
Match on your SKU or the product name
Max. Länge
120
Beispiel
integerstandard1
Page number, from 1 to 10,000
Bereich
1 – 10000
Beispiel
integerstandard20
Items per page (max 100)
Bereich
1 – 100
Beispiel

application/json

object[]
One page of results
string
The shop's own catalogue key for the listing. A seller's identifier, not ours: it is what PATCH /v1/vendor/offers/{sku} addresses.
OfferTargetKind
What a seller listing is for.
string
Slug of the catalogued record the listing points at, in whichever catalog targetKind names.
integer
Price in integer minor units of currency, so cents for AUD. Never a float. Format with Intl.NumberFormat at render rather than dividing first.
string
ISO 4217 code the price is in, e.g. AUD. Prices are integer minor units; format with Intl.NumberFormat at render rather than dividing first.
string
Absolute, directly fetchable URL.
boolean
Whether the shop reports it in stock. Derived from stockQty where the shop tracks a count.
integer | null
Units you hold: 0 is out of stock, null is not tracked. Private to the shop, and never returned by a public offers endpoint.
OfferStatus
Whether a seller listing is public.
string
Where the record came from: a curated entry, an inference, or an import.
integer
Outbound clicks this listing earned over the last 30 days.
string
When a field we serve last changed.
number
Current page number
number
Items per page
number
Total matching records (Builder and above)

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Alle Anfragelimits

Mindeststufe: Enterprise
Monatskontingent: 1,000,000/mo
Anfragerate: 300/min
Tageslimit: 50,000

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.vendor.listOffers();6console.log(data);

1{2  "success": true,3  "data": [4    {5      "sku": "AIM-ACRO-P2",6      "targetKind": "attachment",7      "targetId": "aimpoint-acro-p-2",8      "priceCents": 129900,9      "currency": "AUD",10      "url": "https://example-optics.com/products/aimpoint-acro-p-2",11      "inStock": true,12      "stockQty": 4,13      "status": "draft",14      "source": "api",15      "clicks": 37,16      "updatedAt": "2026-09-08 04:11:00"17    }18  ],19  "pagination": {20    "page": 1,21    "limit": 20,22    "per_page": 20,23    "total": 42,24    "totalPages": 325  }26}

Authentifizierung erforderlichEnterprise

client.vendor.pushOffers()

Upsert up to 500 listings keyed by your own SKU. Ids we do not hold come back as unmatched rather than failing the batch; a bad row (a string price, a float) is a 400 with details naming it.

pushOffers(input: PushOffersInput, scope?: VendorScope): Promise<APIResponse<PushOffersResult>>

PUT/v1/vendor/offers

Enterprise

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

string
Which of your shops to act for. Required only when one key is named by more than one shop; GET /v1/vendor/shops lists them
Max. Länge
64
Beispiel

application/json

object[]erforderlich
The listings to upsert, keyed by your own SKU. Up to 500 per request.

application/json

object
The response payload.
integer
Offers accepted and stored.
object[]
Rows naming a record we do not hold. Reported rather than failing the batch, so a mapping error is a review and not a rejected push.
string
The shop's own catalogue key for the listing. A seller's identifier, not ours: it is what PATCH /v1/vendor/offers/{sku} addresses.
OfferTargetKind
What a seller listing is for.
string
The id the row named, which we do not hold.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
413PAYLOAD_TOO_LARGERequest body too large
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Alle Anfragelimits

Mindeststufe: Enterprise
Monatskontingent: 1,000,000/mo
Anfragerate: 300/min
Tageslimit: 50,000

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.vendor.pushOffers({6  offers: [{ sku: 'AIM-ACRO-P2', attachment_id: 'aimpoint-acro-p-2', price_cents: 129900, currency: 'AUD', url: 'https://example-optics.com/products/aimpoint-acro-p-2', in_stock: true, region: 'AU' }],7});8console.log(data);

1{2  "success": true,3  "data": {4    "written": 498,5    "unmatched": [6      {7        "sku": "OLD-SKU-1",8        "targetKind": "attachment",9        "targetId": "not-in-catalog"10      }11    ]12  }13}

Authentifizierung erforderlichEnterprise

client.vendor.updateOffer()

Change one listing. Absent fields are unchanged.

updateOffer(sku: string, input: UpdateOfferInput, scope?: VendorScope): Promise<APIResponse<{ sku: string }>>

PATCH/v1/vendor/offers/{sku}

Enterprise

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

stringerforderlich
Your own SKU for the offer
Beispiel

string
Which of your shops to act for. Required only when one key is named by more than one shop; GET /v1/vendor/shops lists them
Max. Länge
64
Beispiel

application/json

integer
New price in integer minor units of currency. A float is refused.
string
ISO 4217 code the price is in, e.g. AUD. Prices are integer minor units; format with Intl.NumberFormat at render rather than dividing first.
string
Product page on your shop. Must be a full https:// address; any other scheme is refused.
integer
Units you hold: 0 is out of stock, null is not tracked. Send this or in_stock, never both: a row carrying a quantity derives its flag from it.
boolean
Stock flag, for a shop that does not count units. Send this or stock_qty, never both.
string | null
ISO 3166-1 alpha-2 code you ship to. Null states no restriction.
string
Set published to show the listing on public pages, or draft to take it off them while keeping it.

application/json

object
The response payload.
string
The shop's own catalogue key for the listing. A seller's identifier, not ours: it is what PATCH /v1/vendor/offers/{sku} addresses.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
404NOT_FOUNDResource not found
413PAYLOAD_TOO_LARGERequest body too large
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Alle Anfragelimits

Mindeststufe: Enterprise
Monatskontingent: 1,000,000/mo
Anfragerate: 300/min
Tageslimit: 50,000

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.vendor.updateOffer('AIM-ACRO-P2', {6  price_cents: 139900,7  currency: 'AUD',8  url: 'https://example-optics.com/products/aimpoint-acro-p-2',9  stock_qty: 0,10  in_stock: false,11  region: 'AU',12  status: 'published',13});14console.log(data);

1{2  "success": true,3  "data": {4    "sku": "AIM-ACRO-P2"5  }6}

Authentifizierung erforderlichEnterprise

client.vendor.deleteOffer()

Withdraw one listing.

deleteOffer(sku: string, scope?: VendorScope): Promise<APIResponse<{ removed: boolean }>>

DELETE/v1/vendor/offers/{sku}

Enterprise

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

stringerforderlich
Your own SKU for the offer
Beispiel

string
Which of your shops to act for. Required only when one key is named by more than one shop; GET /v1/vendor/shops lists them
Max. Länge
64
Beispiel

application/json

object
The response payload.
boolean
Always true: the SKU is not listed once this returns, whether or not it was before.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Alle Anfragelimits

Mindeststufe: Enterprise
Monatskontingent: 1,000,000/mo
Anfragerate: 300/min
Tageslimit: 50,000

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.vendor.deleteOffer('AIM-ACRO-P2');6console.log(data);

1{2  "success": true,3  "data": {4    "removed": true5  }6}

ÖffentlichExplorer+

client.vendor.clickUrl()

The tracked outbound link for an offer's clickId. Render this as the href: the API counts the visit and 302s to the shop, so the seller can check our figure against their own analytics.

clickUrl(clickId: string, locale?: 'en' | 'de'): string

GET/v1/out/{clickId}

Explorer+

Keine Authentifizierung. Dieser Endpunkt antwortet ohne Schlüssel.

stringerforderlich
The listing's tracking token, from clickId on an offer

string
Locale for the catalog page a lapsed listing falls back to
Akzeptiert

404NOT_FOUNDResource not found
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Alle Anfragelimits

Mindeststufe: Explorer+
Monatskontingent: 200/mo
Anfragerate: 10/min
Tageslimit: 50

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.vendor.clickUrl('example');6console.log(data);

Diese Antwort hat keinen Body.

ÖffentlichExplorer+

client.vendor.resolveClick()

Follow a click server-side and return the shop URL it lands on. The API counts this as a visit exactly as a browser's would; use it for a link checker, not for rendering. null when the runtime hides cross-origin redirects (browsers do).

resolveClick(clickId: string): Promise<string | null>

GET/v1/out/{clickId}

Explorer+

Keine Authentifizierung. Dieser Endpunkt antwortet ohne Schlüssel.

stringerforderlich
The listing's tracking token, from clickId on an offer

string
Locale for the catalog page a lapsed listing falls back to
Akzeptiert

404NOT_FOUNDResource not found
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Alle Anfragelimits

Mindeststufe: Explorer+
Monatskontingent: 200/mo
Anfragerate: 10/min
Tageslimit: 50

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.vendor.resolveClick('example');6console.log(data);

Diese Antwort hat keinen Body.

Vendor

AutorisierungEnterprise

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungEnterprise

Abfrageparameter

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungEnterprise

Abfrageparameter

Anfrage-Bodyapplication/json

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungEnterprise

Pfadparameter

Abfrageparameter

Anfrage-Bodyapplication/json

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungEnterprise

Pfadparameter

Abfrageparameter

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungExplorer+

Pfadparameter

Abfrageparameter

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungExplorer+

Pfadparameter

Abfrageparameter

Fehler

AnfragelimitsAlle Anfragelimits

Enterprise

application/json

Alle Anfragelimits

Enterprise

application/json

Alle Anfragelimits

Enterprise

application/json

application/json

Alle Anfragelimits

Enterprise

application/json

application/json

Alle Anfragelimits

Enterprise

application/json

Alle Anfragelimits

Explorer+

Alle Anfragelimits

Explorer+

Alle Anfragelimits