Skip to content
BuildBase
HTTP API menu

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

FieldTypeRequiredConstraintsDescription
workspaceIdstringYes--
idstringYesmatches ^[a-f0-9]{24}$-

Send the body as application/json.

Body

FieldTypeRequiredConstraintsDescription
titlestringYesat most 100 characters-
slugstringYesat most 100 characters-
summarystringNoat most 200 characters-
descriptionstringNoat most 20000 characters-
mediaarray of stringNoat most 8 items-
ctaTextstringNoat most 40 characters-
variantsarray of objectYesat least 1 items, at most 250 items-
variants[].idstringYes1 to 64 characters-
variants[].labelstringNoat most 126 characters-
variants[].optionValuesobjectNo--
variants[].rankintegerNoat least 0, at most 1000-
variants[].pricesarray of objectYesat most 40 items-
variants[].prices[].idstringYes1 to 64 characters-
variants[].prices[].currencystringYesmatches ^[a-z]{3}$-
variants[].prices[].modestringYesone of "fixed", "free", "pwyw"-
variants[].prices[].amountintegerNoat least 0, at most 10000000000-
variants[].prices[].compareAtAmountintegerNoat least 0, at most 10000000000-
variants[].prices[].minimumintegerNoat least 0, at most 10000000000-
variants[].prices[].suggestedintegerNoat least 0, at most 10000000000-
variants[].prices[].maximumintegerNoat least 0, at most 10000000000-
variants[].prices[].recurringobjectNo--
variants[].prices[].recurring.intervalstringNoone of "day", "week", "month", "year"-
variants[].prices[].recurring.intervalCountintegerNoat least 1, at most 365-
variants[].prices[].recurring.trialDaysintegerNoat least 0, at most 730-
variants[].prices[].recurring.endAfterPaymentsintegerNoat least 1, at most 1000-
variants[].prices[].recurring.introobjectNo--
variants[].prices[].recurring.intro.amountintegerNoat least 0, at most 10000000000-
variants[].prices[].recurring.intro.periodsintegerNoat least 1, at most 100-
variants[].prices[].depositobjectNo--
variants[].prices[].deposit.percentBpsintegerNoat least 0, at most 10000-
variants[].prices[].milestonesarray of objectNoat most 6 items-
variants[].prices[].milestones[].labelstringNoat most 60 characters-
variants[].prices[].milestones[].percentBpsintegerNoat least 0, at most 10000-
variants[].prices[].installmentsobjectNo--
variants[].prices[].installments.countintegerNoat least 2, at most 60-
variants[].prices[].installments.intervalstringNoone of "week", "month", "year"-
variants[].prices[].installments.intervalCountintegerNoat least 1, at most 12-
variants[].prices[].retiredbooleanNo--
variants[].stockobjectYes--
variants[].stock.modestringYesone of "none", "single", "counted"-
variants[].stock.availableintegerNoat least 0, at most 1000000-
variants[].stock.perBuyerLimitintegerNoat least 1, at most 1000000-
variants[].benefitIdsarray of stringNoat most 50 items-
variants[].dataobjectNo--
variants[].termsstringNoat most 5000 characters-
variants[].salesWindowobjectNo--
variants[].salesWindow.startsAtstringNoat most 40 characters-
variants[].salesWindow.endsAtstringNoat most 40 characters-
variants[].quantityobjectNo--
variants[].quantity.minintegerNoat least 1, at most 1000000-
variants[].quantity.maxintegerNoat least 1, at most 1000000-
variants[].grantsPerUnitintegerNoat least 1, at most 100-
variants[].releasesAtstringNoat most 40 characters-
variants[].bookingSlotsintegerNoat least 0, at most 100-
variants[].weightGramsintegerNoat least 1, at most 1000000-
variants[].dimsMmobjectNo--
variants[].dimsMm.lengthintegerNoat least 1, at most 5000-
variants[].dimsMm.widthintegerNoat least 1, at most 5000-
variants[].dimsMm.heightintegerNoat least 1, at most 5000-
variants[].customsobjectNo--
variants[].customs.hsCodestring or nullNoat most 20 characters-
variants[].customs.originCountrystring or nullNoat most 2 characters-
variants[].customs.descriptionstring or nullNoat most 50 characters-
dataobjectNo--
benefitsarray of objectNoat most 50 items-
benefits[].idstringNo1 to 64 characters-
benefits[].kindstringNoone of "file", "link", "message", "license_key", "access", "manual", "webhook_only", "transfer", "item"-
benefits[].titlestringNoat most 120 characters-
benefits[].afterDaysintegerNoat least 0, at most 3650-
benefits[].availableAtstringNoat most 40 characters-
benefits[].usesintegerNoat least 1, at most 10000-
benefits[].seriesIdstringNoat most 64 characters-
benefits[].updatePolicystringNoone of "latest", "purchased", "until"-
benefits[].updateMonthsintegerNoat least 1, at most 120-
benefits[].downloadLimitintegerNoat least 1, at most 10000-
benefits[].urlstringNoat most 2000 characters-
benefits[].durationDaysintegerNoat least 1, at most 36500-
benefits[].textstringNoat most 5000 characters-
benefits[].activationLimitintegerNoat least 1, at most 10000-
benefits[].expiresInDaysintegerNoat least 1, at most 36500-
benefits[].sourcestringNoone of "generated", "seller_list"-
benefits[].resourceTypestringNoat most 64 characters-
benefits[].resourceIdstringNoat most 128 characters-
benefits[].instructionsstringNoat most 2000 characters-
benefits[].itemIdstringNoat most 64 characters-
benefits[].variantIdstringNoat most 64 characters-
benefits[].quantityintegerNoat least 1, at most 100-
resourceRefstringNoat most 128 characters-
refundPolicystringNoat most 2000 characters-
addOnsarray of objectNoat most 20 items-
addOns[].idstringNo1 to 64 characters-
addOns[].labelstringNoat most 60 characters-
addOns[].pricesarray of objectNoat most 40 items-
addOns[].prices[].idstringNo1 to 64 characters-
addOns[].prices[].currencystringNomatches ^[a-z]{3}$-
addOns[].prices[].modestringNoone of "fixed", "free", "pwyw"-
addOns[].prices[].amountintegerNoat least 0, at most 10000000000-
addOns[].prices[].compareAtAmountintegerNoat least 0, at most 10000000000-
addOns[].prices[].minimumintegerNoat least 0, at most 10000000000-
addOns[].prices[].suggestedintegerNoat least 0, at most 10000000000-
addOns[].prices[].maximumintegerNoat least 0, at most 10000000000-
addOns[].prices[].recurringobjectNo--
addOns[].prices[].recurring.intervalstringNoone of "day", "week", "month", "year"-
addOns[].prices[].recurring.intervalCountintegerNoat least 1, at most 365-
addOns[].prices[].recurring.trialDaysintegerNoat least 0, at most 730-
addOns[].prices[].recurring.endAfterPaymentsintegerNoat least 1, at most 1000-
addOns[].prices[].recurring.introobjectNo--
addOns[].prices[].recurring.intro.amountintegerNoat least 0, at most 10000000000-
addOns[].prices[].recurring.intro.periodsintegerNoat least 1, at most 100-
addOns[].prices[].depositobjectNo--
addOns[].prices[].deposit.percentBpsintegerNoat least 0, at most 10000-
addOns[].prices[].milestonesarray of objectNoat most 6 items-
addOns[].prices[].milestones[].labelstringNoat most 60 characters-
addOns[].prices[].milestones[].percentBpsintegerNoat least 0, at most 10000-
addOns[].prices[].installmentsobjectNo--
addOns[].prices[].installments.countintegerNoat least 2, at most 60-
addOns[].prices[].installments.intervalstringNoone of "week", "month", "year"-
addOns[].prices[].installments.intervalCountintegerNoat least 1, at most 12-
addOns[].prices[].retiredbooleanNo--
addOns[].maxQuantityintegerNoat least 1, at most 1000-
addOns[].benefitIdsarray of stringNoat most 50 items-
payeesarray of objectNoat most 10 items-
payees[].sellerIdstringNoat most 64 characters-
payees[].shareBpsintegerNoat least 0, at most 10000-
eligibilityobjectNo--
eligibility.requiresItemIdstringNoat most 64 characters-
eligibility.minRankintegerNoat least 0, at most 1000-
eligibility.buyerIdsarray of stringNoat most 100 items-
capacityintegerNoat least 0, at most 1000000-
questionsarray of objectNoat most 20 items-
questions[].slugstringNoat most 64 characters-
questions[].titlestringNoat most 120 characters-
questions[].helpTextstringNoat most 500 characters-
questions[].typestringNoat most 20 characters-
questions[].requiredbooleanNo--
questions[].defaultValuestring or number or boolean or nullNoat most 1000 characters-
questions[].optionsarray of objectNoat most 200 items-
questions[].options[].valuestringNoat most 120 characters-
questions[].options[].labelstringNoat most 120 characters-
questions[].minnumberNo--
questions[].maxnumberNo--
questions[].patternstringNoat most 200 characters-
questions[].currencystringNomatches ^[a-z]{3}$-
questions[].visibilitystringNoone of "public", "after_purchase", "seller_only", "app_only"-
questions[].filterablebooleanNo--
questions[].sortablebooleanNo--
questions[].uniquePerOwnerbooleanNo--
questions[].maxMbnumberNoat least 0.1, at most 100-
questions[].maxFilesintegerNoat least 1, at most 10-
questions[].perstringNoone of "order", "unit"-
questions[].variantIdsarray of stringNoat most 250 items-
shippingobjectNo--
shipping.countriesarray of stringNoat most 250 items-
shipping.regionsarray of stringNoat most 500 items-
shipping.flatRateintegerNoat least 0, at most 10000000000-
shipping.additionalRateintegerNoat least 0, at most 10000000000-
shipping.packagingGramsintegerNoat least 0, at most 1000000-
shipping.pickupbooleanNo--
taxCodestringNoat most 20 characters-
buyerCountriesarray of stringNoat most 250 items-
customsobjectNo--
customs.hsCodestring or nullNoat most 20 characters-
customs.originCountrystring or nullNoat most 2 characters-
customs.descriptionstring or nullNoat most 50 characters-
optionsarray of objectNoat most 3 items-
options[].idstringNo1 to 16 characters-
options[].namestringNoat most 40 characters-
options[].valuesarray of objectNoat most 20 items-
options[].values[].idstringNo1 to 16 characters-
options[].values[].labelstringNoat most 40 characters-
options[].values[].retiredbooleanNo--
bookingobjectNo--
booking.calendarIdstringNomatches ^[a-f0-9]{24}$-
booking.timeZonestringNoat most 64 characters-
booking.slotMinutesintegerNoat least 0, at most 720-
booking.bufferMinutesintegerNoat least 0, at most 240-
booking.bufferBeforeMinutesintegerNoat least 0, at most 240-
booking.seatsPerSlotintegerNoat least 0, at most 1000-
booking.weeklyobjectNo--
booking.weekly.monarray of objectNoat most 6 items-
booking.weekly.mon[].fromstringNoat most 5 characters-
booking.weekly.mon[].tostringNoat most 5 characters-
booking.weekly.tuearray of objectNoat most 6 items-
booking.weekly.tue[].fromstringNoat most 5 characters-
booking.weekly.tue[].tostringNoat most 5 characters-
booking.weekly.wedarray of objectNoat most 6 items-
booking.weekly.wed[].fromstringNoat most 5 characters-
booking.weekly.wed[].tostringNoat most 5 characters-
booking.weekly.thuarray of objectNoat most 6 items-
booking.weekly.thu[].fromstringNoat most 5 characters-
booking.weekly.thu[].tostringNoat most 5 characters-
booking.weekly.friarray of objectNoat most 6 items-
booking.weekly.fri[].fromstringNoat most 5 characters-
booking.weekly.fri[].tostringNoat most 5 characters-
booking.weekly.satarray of objectNoat most 6 items-
booking.weekly.sat[].fromstringNoat most 5 characters-
booking.weekly.sat[].tostringNoat most 5 characters-
booking.weekly.sunarray of objectNoat most 6 items-
booking.weekly.sun[].fromstringNoat most 5 characters-
booking.weekly.sun[].tostringNoat most 5 characters-
booking.exceptionsarray of objectNoat most 200 items-
booking.exceptions[].datestringNoat most 10 characters-
booking.exceptions[].windowsarray of objectNoat most 6 items-
booking.exceptions[].windows[].fromstringNoat most 5 characters-
booking.exceptions[].windows[].tostringNoat most 5 characters-
booking.minNoticeMinutesintegerNoat least 0, at most 43200-
booking.maxDaysAheadintegerNoat least 0, at most 365-
booking.buyerCancelobject or nullNo--
booking.buyerCancel.minutesBeforeintegerNoat least 0, at most 43200-
booking.buyerCancel.refundstringNoone of "full", "none"-
booking.buyerRescheduleobject or nullNo--
booking.buyerReschedule.minutesBeforeintegerNoat least 0, at most 43200-
booking.buyerReschedule.maxTimesintegerNoat least 0, at most 10-
booking.seatsPerUnitintegerNoat least 0, at most 100-
booking.seatsCapintegerNoat least 0, at most 1000-
booking.bookingLimitsobject or nullNo--
booking.bookingLimits.perDayinteger or nullNoat least 0, at most 1000-
booking.bookingLimits.perWeekinteger or nullNoat least 0, at most 1000-
booking.remindersarray of objectNoat most 3 items-
booking.reminders[].minutesBeforeintegerNoat 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.text

Responses

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.

Example
{
  "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.

Example
Unauthorized

429 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.

Example
{
  "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: