Save the whole content of an item the signed-in user sells
Replaces the item's content under the item type's live version; a live item stays live unless the type re-reviews edits, and must still meet what going live...
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/me/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).
Replaces the item's content under the item type's live version; a live item stays live unless the type re-reviews edits, and must still meet what going live needs. Refused with 409 when the slug is taken or the item changed meanwhile, and 422 when the content does not meet the type.
Request
Path parameters
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
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/me/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/me/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/me/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
- All Me 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
me.items.updatein public-v1.json