Skip to content
Handbid Developers

POST /v3/vendor/products — create product

POST
/v3/vendor/products
 
curl --request POST \
  --url https://api-ha-prod-p8.handbid.dev/v3/vendor/products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "productCode": "WIN-1", "name": "Napa Getaway", "reservePrice": 2000, "value": 4500, "inventoryQuantity": 3, "isPublic": 0, "taxonomyId": 12 }'

Create a marketplace package in your vendor catalog.

Idempotent SKU replay: a repeat POST with a productCode already in your catalog does not create a duplicate — it returns 204 with the Location of the existing package. Safe to retry.

Body: productCode, name, reservePrice and value are required.

Responses:

  • 204 No Content — created, or the existing package on an idempotent SKU replay. The Location header points at the package.
  • 422 validation_error — a required field is missing or a field failed validation.
  • 503 unavailable — transient lock contention on the catalog; the envelope carries a retryAfter (seconds). Safe to retry.
  • 401 unauthorized / 403 forbidden — as for the list endpoint.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
productCode
required

Vendor SKU. A repeat POST with the same code is an idempotent replay.

string
name
required
string
reservePrice
required

Vendor cost / floor, in dollars.

number
value
required

Retail (fair-market) value, in dollars.

number
inventoryQuantity
integer
isPublic

0 = private (default), 1 = publicly listable.

integer
taxonomyId
integer
Example 
{
  "productCode": "WIN-1",
  "name": "Napa Getaway",
  "reservePrice": 2000,
  "value": 4500,
  "inventoryQuantity": 3,
  "isPublic": 0,
  "taxonomyId": 12
}

Responses

Section titled “ Responses ”

204

Section titled “204 ”

Created — or the existing package on an idempotent SKU replay.

Headers

Section titled “Headers ”
Location
string

URL of the created (or existing) package.

401

Section titled “401 ”

No or invalid Bearer token.

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example 
{
  "error": "unauthorized",
  "message": "A valid Bearer token is required."
}

403

Section titled “403 ”

The token’s organization is not a marketplace vendor.

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example 
{
  "error": "forbidden",
  "message": "Your organization is not a marketplace vendor."
}

422

Section titled “422 ”

Validation error.

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example 
{
  "error": "validation_error",
  "message": "productCode, name, reservePrice and value are required."
}

503

Section titled “503 ”

Transient lock contention on the catalog. Retry after the indicated delay.

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example 
{
  "error": "unavailable",
  "message": "The catalog is briefly locked; please retry.",
  "retryAfter": 2
}