Replace the content of one of the workspace's items
Needs workspace:selling:manage.
Warning
Not fully described yet. The API description has no described successful answer for this operation yet. The method, path, sign-in, rate limits and request fields on this page are read from the server's code and are accurate; what a successful call returns is not written down here yet. Until it is, search engines and the agent index leave this page out.
PUT/api/v1/public/workspaces/workspaceId/items/id
- Sign-in
- A signed-in user's session: send the session id in the x-session-id header.
- Rate limit
- Up to 500 requests every 3 seconds per IP address; up to 1,000 requests a minute per API key (some requests are not counted).
Needs workspace:selling:manage. Invalid content answers 422 ITEM_INVALID; a concurrent change answers 409 ITEM_STATE_CONFLICT.
Request
Path parameters
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
workspaceId | string | Yes | - | - |
id | string | Yes | matches ^[a-f0-9]{24}$ | - |
Send the body as application/json.
Body
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
title | string | Yes | at most 100 characters | - |
slug | string | Yes | at most 100 characters | - |
summary | string | No | at most 200 characters | - |
description | string | No | at most 20000 characters | - |
media | array of string | No | at most 8 items | - |
ctaText | string | No | at most 40 characters | - |
variants | array of object | Yes | at least 1 items, at most 250 items | - |
variants[].id | string | Yes | 1 to 64 characters | - |
variants[].label | string | No | at most 126 characters | - |
variants[].optionValues | object | No | - | - |
variants[].rank | integer | No | at least 0, at most 1000 | - |
variants[].prices | array of object | Yes | at most 40 items | - |
variants[].prices[].id | string | Yes | 1 to 64 characters | - |
variants[].prices[].currency | string | Yes | matches ^[a-z]{3}$ | - |
variants[].prices[].mode | string | Yes | one of "fixed", "free", "pwyw" | - |
variants[].prices[].amount | integer | No | at least 0, at most 10000000000 | - |
variants[].prices[].compareAtAmount | integer | No | at least 0, at most 10000000000 | - |
variants[].prices[].minimum | integer | No | at least 0, at most 10000000000 | - |
variants[].prices[].suggested | integer | No | at least 0, at most 10000000000 | - |
variants[].prices[].maximum | integer | No | at least 0, at most 10000000000 | - |
variants[].prices[].recurring | object | No | - | - |
variants[].prices[].recurring.interval | string | No | one of "day", "week", "month", "year" | - |
variants[].prices[].recurring.intervalCount | integer | No | at least 1, at most 365 | - |
variants[].prices[].recurring.trialDays | integer | No | at least 0, at most 730 | - |
variants[].prices[].recurring.endAfterPayments | integer | No | at least 1, at most 1000 | - |
variants[].prices[].recurring.intro | object | No | - | - |
variants[].prices[].recurring.intro.amount | integer | No | at least 0, at most 10000000000 | - |
variants[].prices[].recurring.intro.periods | integer | No | at least 1, at most 100 | - |
variants[].prices[].deposit | object | No | - | - |
variants[].prices[].deposit.percentBps | integer | No | at least 0, at most 10000 | - |
variants[].prices[].milestones | array of object | No | at most 6 items | - |
variants[].prices[].milestones[].label | string | No | at most 60 characters | - |
variants[].prices[].milestones[].percentBps | integer | No | at least 0, at most 10000 | - |
variants[].prices[].installments | object | No | - | - |
variants[].prices[].installments.count | integer | No | at least 2, at most 60 | - |
variants[].prices[].installments.interval | string | No | one of "week", "month", "year" | - |
variants[].prices[].installments.intervalCount | integer | No | at least 1, at most 12 | - |
variants[].prices[].retired | boolean | No | - | - |
variants[].stock | object | Yes | - | - |
variants[].stock.mode | string | Yes | one of "none", "single", "counted" | - |
variants[].stock.available | integer | No | at least 0, at most 1000000 | - |
variants[].stock.perBuyerLimit | integer | No | at least 1, at most 1000000 | - |
variants[].benefitIds | array of string | No | at most 50 items | - |
variants[].data | object | No | - | - |
variants[].terms | string | No | at most 5000 characters | - |
variants[].salesWindow | object | No | - | - |
variants[].salesWindow.startsAt | string | No | at most 40 characters | - |
variants[].salesWindow.endsAt | string | No | at most 40 characters | - |
variants[].quantity | object | No | - | - |
variants[].quantity.min | integer | No | at least 1, at most 1000000 | - |
variants[].quantity.max | integer | No | at least 1, at most 1000000 | - |
variants[].grantsPerUnit | integer | No | at least 1, at most 100 | - |
variants[].releasesAt | string | No | at most 40 characters | - |
variants[].bookingSlots | integer | No | at least 0, at most 100 | - |
variants[].weightGrams | integer | No | at least 1, at most 1000000 | - |
variants[].dimsMm | object | No | - | - |
variants[].dimsMm.length | integer | No | at least 1, at most 5000 | - |
variants[].dimsMm.width | integer | No | at least 1, at most 5000 | - |
variants[].dimsMm.height | integer | No | at least 1, at most 5000 | - |
variants[].customs | object | No | - | - |
variants[].customs.hsCode | string or null | No | at most 20 characters | - |
variants[].customs.originCountry | string or null | No | at most 2 characters | - |
variants[].customs.description | string or null | No | at most 50 characters | - |
data | object | No | - | - |
benefits | array of object | No | at most 50 items | - |
benefits[].id | string | No | 1 to 64 characters | - |
benefits[].kind | string | No | one of "file", "link", "message", "license_key", "access", "manual", "webhook_only", "transfer", "item" | - |
benefits[].title | string | No | at most 120 characters | - |
benefits[].afterDays | integer | No | at least 0, at most 3650 | - |
benefits[].availableAt | string | No | at most 40 characters | - |
benefits[].uses | integer | No | at least 1, at most 10000 | - |
benefits[].seriesId | string | No | at most 64 characters | - |
benefits[].updatePolicy | string | No | one of "latest", "purchased", "until" | - |
benefits[].updateMonths | integer | No | at least 1, at most 120 | - |
benefits[].downloadLimit | integer | No | at least 1, at most 10000 | - |
benefits[].url | string | No | at most 2000 characters | - |
benefits[].durationDays | integer | No | at least 1, at most 36500 | - |
benefits[].text | string | No | at most 5000 characters | - |
benefits[].activationLimit | integer | No | at least 1, at most 10000 | - |
benefits[].expiresInDays | integer | No | at least 1, at most 36500 | - |
benefits[].source | string | No | one of "generated", "seller_list" | - |
benefits[].resourceType | string | No | at most 64 characters | - |
benefits[].resourceId | string | No | at most 128 characters | - |
benefits[].instructions | string | No | at most 2000 characters | - |
benefits[].itemId | string | No | at most 64 characters | - |
benefits[].variantId | string | No | at most 64 characters | - |
benefits[].quantity | integer | No | at least 1, at most 100 | - |
resourceRef | string | No | at most 128 characters | - |
refundPolicy | string | No | at most 2000 characters | - |
addOns | array of object | No | at most 20 items | - |
addOns[].id | string | No | 1 to 64 characters | - |
addOns[].label | string | No | at most 60 characters | - |
addOns[].prices | array of object | No | at most 40 items | - |
addOns[].prices[].id | string | No | 1 to 64 characters | - |
addOns[].prices[].currency | string | No | matches ^[a-z]{3}$ | - |
addOns[].prices[].mode | string | No | one of "fixed", "free", "pwyw" | - |
addOns[].prices[].amount | integer | No | at least 0, at most 10000000000 | - |
addOns[].prices[].compareAtAmount | integer | No | at least 0, at most 10000000000 | - |
addOns[].prices[].minimum | integer | No | at least 0, at most 10000000000 | - |
addOns[].prices[].suggested | integer | No | at least 0, at most 10000000000 | - |
addOns[].prices[].maximum | integer | No | at least 0, at most 10000000000 | - |
addOns[].prices[].recurring | object | No | - | - |
addOns[].prices[].recurring.interval | string | No | one of "day", "week", "month", "year" | - |
addOns[].prices[].recurring.intervalCount | integer | No | at least 1, at most 365 | - |
addOns[].prices[].recurring.trialDays | integer | No | at least 0, at most 730 | - |
addOns[].prices[].recurring.endAfterPayments | integer | No | at least 1, at most 1000 | - |
addOns[].prices[].recurring.intro | object | No | - | - |
addOns[].prices[].recurring.intro.amount | integer | No | at least 0, at most 10000000000 | - |
addOns[].prices[].recurring.intro.periods | integer | No | at least 1, at most 100 | - |
addOns[].prices[].deposit | object | No | - | - |
addOns[].prices[].deposit.percentBps | integer | No | at least 0, at most 10000 | - |
addOns[].prices[].milestones | array of object | No | at most 6 items | - |
addOns[].prices[].milestones[].label | string | No | at most 60 characters | - |
addOns[].prices[].milestones[].percentBps | integer | No | at least 0, at most 10000 | - |
addOns[].prices[].installments | object | No | - | - |
addOns[].prices[].installments.count | integer | No | at least 2, at most 60 | - |
addOns[].prices[].installments.interval | string | No | one of "week", "month", "year" | - |
addOns[].prices[].installments.intervalCount | integer | No | at least 1, at most 12 | - |
addOns[].prices[].retired | boolean | No | - | - |
addOns[].maxQuantity | integer | No | at least 1, at most 1000 | - |
addOns[].benefitIds | array of string | No | at most 50 items | - |
payees | array of object | No | at most 10 items | - |
payees[].sellerId | string | No | at most 64 characters | - |
payees[].shareBps | integer | No | at least 0, at most 10000 | - |
eligibility | object | No | - | - |
eligibility.requiresItemId | string | No | at most 64 characters | - |
eligibility.minRank | integer | No | at least 0, at most 1000 | - |
eligibility.buyerIds | array of string | No | at most 100 items | - |
capacity | integer | No | at least 0, at most 1000000 | - |
questions | array of object | No | at most 20 items | - |
questions[].slug | string | No | at most 64 characters | - |
questions[].title | string | No | at most 120 characters | - |
questions[].helpText | string | No | at most 500 characters | - |
questions[].type | string | No | at most 20 characters | - |
questions[].required | boolean | No | - | - |
questions[].defaultValue | string or number or boolean or null | No | at most 1000 characters | - |
questions[].options | array of object | No | at most 200 items | - |
questions[].options[].value | string | No | at most 120 characters | - |
questions[].options[].label | string | No | at most 120 characters | - |
questions[].min | number | No | - | - |
questions[].max | number | No | - | - |
questions[].pattern | string | No | at most 200 characters | - |
questions[].currency | string | No | matches ^[a-z]{3}$ | - |
questions[].visibility | string | No | one of "public", "after_purchase", "seller_only", "app_only" | - |
questions[].filterable | boolean | No | - | - |
questions[].sortable | boolean | No | - | - |
questions[].uniquePerOwner | boolean | No | - | - |
questions[].maxMb | number | No | at least 0.1, at most 100 | - |
questions[].maxFiles | integer | No | at least 1, at most 10 | - |
questions[].per | string | No | one of "order", "unit" | - |
questions[].variantIds | array of string | No | at most 250 items | - |
shipping | object | No | - | - |
shipping.countries | array of string | No | at most 250 items | - |
shipping.regions | array of string | No | at most 500 items | - |
shipping.flatRate | integer | No | at least 0, at most 10000000000 | - |
shipping.additionalRate | integer | No | at least 0, at most 10000000000 | - |
shipping.packagingGrams | integer | No | at least 0, at most 1000000 | - |
shipping.pickup | boolean | No | - | - |
taxCode | string | No | at most 20 characters | - |
buyerCountries | array of string | No | at most 250 items | - |
customs | object | No | - | - |
customs.hsCode | string or null | No | at most 20 characters | - |
customs.originCountry | string or null | No | at most 2 characters | - |
customs.description | string or null | No | at most 50 characters | - |
options | array of object | No | at most 3 items | - |
options[].id | string | No | 1 to 16 characters | - |
options[].name | string | No | at most 40 characters | - |
options[].values | array of object | No | at most 20 items | - |
options[].values[].id | string | No | 1 to 16 characters | - |
options[].values[].label | string | No | at most 40 characters | - |
options[].values[].retired | boolean | No | - | - |
booking | object | No | - | - |
booking.calendarId | string | No | matches ^[a-f0-9]{24}$ | - |
booking.timeZone | string | No | at most 64 characters | - |
booking.slotMinutes | integer | No | at least 0, at most 720 | - |
booking.bufferMinutes | integer | No | at least 0, at most 240 | - |
booking.bufferBeforeMinutes | integer | No | at least 0, at most 240 | - |
booking.seatsPerSlot | integer | No | at least 0, at most 1000 | - |
booking.weekly | object | No | - | - |
booking.weekly.mon | array of object | No | at most 6 items | - |
booking.weekly.mon[].from | string | No | at most 5 characters | - |
booking.weekly.mon[].to | string | No | at most 5 characters | - |
booking.weekly.tue | array of object | No | at most 6 items | - |
booking.weekly.tue[].from | string | No | at most 5 characters | - |
booking.weekly.tue[].to | string | No | at most 5 characters | - |
booking.weekly.wed | array of object | No | at most 6 items | - |
booking.weekly.wed[].from | string | No | at most 5 characters | - |
booking.weekly.wed[].to | string | No | at most 5 characters | - |
booking.weekly.thu | array of object | No | at most 6 items | - |
booking.weekly.thu[].from | string | No | at most 5 characters | - |
booking.weekly.thu[].to | string | No | at most 5 characters | - |
booking.weekly.fri | array of object | No | at most 6 items | - |
booking.weekly.fri[].from | string | No | at most 5 characters | - |
booking.weekly.fri[].to | string | No | at most 5 characters | - |
booking.weekly.sat | array of object | No | at most 6 items | - |
booking.weekly.sat[].from | string | No | at most 5 characters | - |
booking.weekly.sat[].to | string | No | at most 5 characters | - |
booking.weekly.sun | array of object | No | at most 6 items | - |
booking.weekly.sun[].from | string | No | at most 5 characters | - |
booking.weekly.sun[].to | string | No | at most 5 characters | - |
booking.exceptions | array of object | No | at most 200 items | - |
booking.exceptions[].date | string | No | at most 10 characters | - |
booking.exceptions[].windows | array of object | No | at most 6 items | - |
booking.exceptions[].windows[].from | string | No | at most 5 characters | - |
booking.exceptions[].windows[].to | string | No | at most 5 characters | - |
booking.minNoticeMinutes | integer | No | at least 0, at most 43200 | - |
booking.maxDaysAhead | integer | No | at least 0, at most 365 | - |
booking.buyerCancel | object or null | No | - | - |
booking.buyerCancel.minutesBefore | integer | No | at least 0, at most 43200 | - |
booking.buyerCancel.refund | string | No | one of "full", "none" | - |
booking.buyerReschedule | object or null | No | - | - |
booking.buyerReschedule.minutesBefore | integer | No | at least 0, at most 43200 | - |
booking.buyerReschedule.maxTimes | integer | No | at least 0, at most 10 | - |
booking.seatsPerUnit | integer | No | at least 0, at most 100 | - |
booking.seatsCap | integer | No | at least 0, at most 1000 | - |
booking.bookingLimits | object or null | No | - | - |
booking.bookingLimits.perDay | integer or null | No | at least 0, at most 1000 | - |
booking.bookingLimits.perWeek | integer or null | No | at least 0, at most 1000 | - |
booking.reminders | array of object | No | at most 3 items | - |
booking.reminders[].minutesBefore | integer | No | at least 0, at most 10080 | - |
Example request
Replace each YOUR_... value with your own, and set the credential in the environment variable the sample reads.
curl -X PUT "https://api.console.buildbase.app/api/v1/public/workspaces/YOUR_WORKSPACE_ID/items/YOUR_ID" \
-H "x-session-id: $BUILDBASE_SESSION_ID" \
-H "Content-Type: application/json" \
-d '{
"title": "string",
"slug": "string",
"variants": [
{
"id": "YOUR_ID",
"prices": [
{
"id": "YOUR_ID",
"currency": "string",
"mode": "fixed"
}
],
"stock": {
"mode": "none"
}
}
]
}'const response = await fetch(
'https://api.console.buildbase.app/api/v1/public/workspaces/YOUR_WORKSPACE_ID/items/YOUR_ID',
{
method: 'PUT',
headers: {
'x-session-id': process.env.BUILDBASE_SESSION_ID ?? '',
'Content-Type': 'application/json',
},
body: JSON.stringify({
title: 'string',
slug: 'string',
variants: [
{
id: 'YOUR_ID',
prices: [
{
id: 'YOUR_ID',
currency: 'string',
mode: 'fixed',
},
],
stock: {
mode: 'none',
},
},
],
}),
}
);
if (!response.ok) {
throw new Error(`${response.status}: ${await response.text()}`);
}
const data = await response.text();import os
import requests
response = requests.put(
"https://api.console.buildbase.app/api/v1/public/workspaces/YOUR_WORKSPACE_ID/items/YOUR_ID",
headers={
"x-session-id": os.environ["BUILDBASE_SESSION_ID"],
},
json={
"title": "string",
"slug": "string",
"variants": [
{
"id": "YOUR_ID",
"prices": [
{
"id": "YOUR_ID",
"currency": "string",
"mode": "fixed",
},
],
"stock": {
"mode": "none",
},
},
],
},
timeout=30,
)
response.raise_for_status()
data = response.textResponses
A successful answer is not described yet. The server answers with the status and body its handler sends.
Any other status
The handler's own answer. Not described yet: response bodies come from captured responses (server/openapi/captured) and overlays (server/openapi/overlays).
Errors
Each refusal, what it means, and what to do. The request changed nothing.
400 Bad Request
What it means: The request failed a validate() schema, or an id in the path is not a valid id. path names the field.
What to do: Fix the field the body names in path (or read message) and send the request again. Nothing was changed.
{
"error": true,
"success": false,
"path": "string",
"message": "string"
}401 Unauthorized
What it means: The credential is missing, expired or not accepted here, or the caller's role has no grant for x-permission (refused with 401 too). The body is the plain text Unauthorized, or a JSON body with a code where the gate says why.
What to do: Send the credential this operation asks for (see Sign-in above), or sign in again if it expired. A valid credential is also refused when the role has no grant for the permission above.
Unauthorized429 Too Many Requests
What it means: A rate limit in x-rateLimit was reached. retryAfter and the Retry-After header say how many seconds until the window resets.
What to do: Wait the number of seconds in the Retry-After header (also retryAfter in the body), then retry. Slow down repeated calls.
{
"success": false,
"message": "string",
"reason": "rate_limited",
"retryAfter": 1
}Events
A successful call can send these webhook events to the endpoints that subscribe to them:
Related
- Workspaces guide: how this part of BuildBase works
- All Workspaces operations
- API reference: every operation, by tag
- Sign-in and credentials for the HTTP API
- How the HTTP API reports errors
- Make your first call
- Error codes: every
codethe API returns - OpenAPI: operation
workspaces.items.updatein public-v1.json