Skip to content

For vendors and their developers

Live pricing integration guide

Connect your booking or pricing system so the price list on your profile updates by itself. Three ways to send prices: an HTTPS API, signed webhooks or gRPC.

The short version

  1. Vendor: once your business is verified, open Pricing in your dashboard, choose Live feed and connect your system. You get an address and a credential that is shown once.
  2. Vendor: send your developer or software provider this page and the address. Pass the credential separately, over a secure channel.
  3. Developer: build one method (HTTPS API, webhooks or gRPC) and send the whole price list once. The profile switches to live pricing with that first delivery.
On this page

What live pricing is

Your profile on Vow Portal has one price list. You can keep it up to date in two ways:

  • Static list. You type the prices into the dashboard and change them by hand.
  • Live feed. Your own booking or pricing system sends the prices to us whenever they change. Nobody types anything.

Use the live feed when your prices move often (by season, day of the week, demand or weather) or when they already live in another system and you do not want to keep two copies in step. If your prices change a few times a year, the static list is less work.

With live pricing on, couples see the same price list with one line above it: Live pricing from your system's name, updated 2 hours ago. The name is the one you type when you connect.

One business has one connection and one price list. A connection uses one credential and one method. Connecting again replaces the connection you had.

Before you start

  • Your business must be verified. Until the TL Portraitz team has verified it, the dashboard explains live pricing but does not offer the connection.
  • You need someone who can change what your system sends: your booking software provider, or your own developer.
Who does what
WhoDoes
You, the vendorCreate the connection in the dashboard. Copy the credential, which is shown once, and pass it to the developer over a secure channel (a password manager's sharing feature, not plain email or chat). Send them the link to this guide and the address shown in the dashboard.
Your developer or providerBuilds one of the three methods below, stores the credential on a server, sends a first price list, and tells you when it is done.
You againPress Check connection, look at your public page, and keep an eye on Last sync.

What to send your developer. The dashboard has this ready to copy, with your own address, under Send this to your developer.

Message to your developer example
We would like our prices on Vow Portal to update from our booking system.

Integration guide: https://vowportal.com/developers/pricing
Method: HTTPS API
Endpoint: https://vowportal-b2b.fly.dev/partner/v1

I will send you the API key separately, over a secure channel. Please do not ask for it by email.

Choosing a method

All three methods do the same three things (replace the whole list, add or change one item, remove one item) and write to the same price list. Pick by what your system can do.

Which method to use
Your system…UseIt needs
can call an HTTPS API (most custom or in-house systems, scripts, scheduled jobs)HTTPS APIAn API key (vpk_…), sent as Authorization: Bearer. JSON over HTTPS.
can only send outbound webhooks to a URL with a shared secret (much off-the-shelf booking software)WebhookA webhook URL and a signing secret (whsec_…). Your system signs each delivery with HMAC-SHA256.
already uses gRPC, or you want to stream many changes on one connectiongRPCAn API key (vpk_…), sent as authorization metadata. A client generated from our .proto file. TLS.

If you are not sure, choose the HTTPS API. An API key works on both the HTTPS API and gRPC, whichever of the two you picked in the dashboard; a webhook connection only accepts signed webhooks.

Step by step in the dashboard

The names in bold are the ones on screen.

Connect

  1. Open Pricing in the vendor dashboard.
  2. Under Price source, choose Live feed.
  3. In Connect your booking system, answer How will your system send prices? with gRPC, HTTPS API or Webhook.
  4. Fill in Your system's name (up to 80 characters), for example the name of your booking software. Couples see it next to your live prices.
  5. Press Connect and get credentials.

Your profile does not change yet. The static list stays on your page until the first prices arrive.

Copy the credential (shown once)

A card titled Your new API key (or Your new signing secret) appears. Press Copy and store the value in a password manager or straight in your system. This is the only time it is shown: after you leave or reload the page it cannot be shown again, by you or by us. If you lose it, rotate it.

Where the addresses are

The Live pricing feed panel shows the address under Endpoint (or Webhook URL) with a Copy button. Always use the address shown there. The production addresses are currently:

Production addresses
MethodAddress
HTTPS APIhttps://vowportal-b2b.fly.dev/partner/v1
Webhookhttps://vowportal-b2b.fly.dev/webhooks/pricing/feed_… (ends with your connection's id)
gRPCvowportal-b2b.fly.dev:8443 (TLS)

Connection states

Connection states
BadgeMeaning
Waiting for the first pricesThe connection exists and nothing has been delivered. Your profile still shows your static list.
ConnectedAt least one delivery has been applied. Last sync says when the latest one arrived, Revision which one it was (rev_1, rev_2, …).
Stale, DisconnectedReserved. Nothing sets these on its own today: a connection that stops sending stays Connected, and Last sync is how you notice. Couples keep seeing the last prices received.

Check connection does not send anything to your system. It reports whether a delivery has arrived.

Which list is on your profile

The line On your profile now: says Static list or Live feed.

  • The first delivery switches your profile to the live feed and replaces the static list with what was delivered. This happens once.
  • To go back to your own list, choose Static list, edit it (it starts as a copy of the live prices) and press Save and switch to these prices.
  • While your profile shows the static list, your system can keep sending. Deliveries are accepted and stored but not shown, and no delivery switches the profile back by itself.
  • To show the live prices again, choose Live feed and press Use live pricing. Your profile then shows the latest prices your system delivered.

Rotate the credential

Press Rotate key (or Rotate secret) and confirm. A new credential is shown once.

  • API key: the old key stops working immediately, including on a gRPC stream that is open. Update your system right away.
  • Signing secret: the old secret keeps being accepted for 24 hours, so you can update your system without losing deliveries. Only one old secret is kept: rotating twice within 24 hours ends the first one at once.

Disconnect

Press Disconnect and confirm. The credential stops working, your profile goes back to a static list that starts with the prices shown at that moment, and you edit it by hand from then on. Connecting again later creates a new connection: a new credential, and for webhooks a new URL. What the old connection delivered is not carried over, and the profile switches to the live feed again with the new connection's first delivery.

The data model

A price item

Fields of a price item
Field (JSON)TypeRequiredRules
skustringyesYour stable identifier for the item. 1 to 64 characters. Unique within a sheet. Changes and removals match on it exactly (case-sensitive). Use letters, digits, -, _ and . so it needs no escaping in a URL. One page design shows the SKU to couples, so do not put anything private in it.
namestringyes1 to 120 characters. What couples read, for example "Saturday, peak season".
descriptionstringnoUp to 500 characters.
amount_minorintegeryesThe price in the currency's minor unit (cents). 1450000 is $14,500.00. From 0 to 100,000,000 ($1,000,000.00). A whole number, never a decimal and never a string. It must be there: a missing or null amount is refused, never read as 0. To list an item as free, send 0.
currencystringyesCAD. The portal lists prices in Canadian dollars; no other currency is accepted.
unitstringyesOne of per_event, per_hour, per_person, starting_at.
valid_fromdatenoYYYY-MM-DD.
valid_untildatenoYYYY-MM-DD. Not before valid_from.

Lengths count characters, not bytes.

  • Required means required. A required field that is missing or null is refused (422); nothing is filled in for it. A price of zero is a real price, so it has to be sent as 0. Over gRPC, where a number that was left out cannot be told from 0, it is the price message that must be set.
  • Field names are exact. In the HTTPS API and in webhooks, field names are lowercase and matched exactly. An unknown field, a known one in another case ("Name") and a field that appears twice in one object are all refused (400), so send each documented field once and nothing else.
  • Text must be clean. sku, name, description, notes and a webhook's event_id are shown or stored as you send them, so they are refused (422, INVALID_ARGUMENT), not cleaned, when they are not valid UTF-8 or contain any of the characters below.
Characters refused in text
KindCode points
Control charactersU+0000 to U+001F and U+007F to U+009F. The one exception: a line break (U+000A, U+000D) is allowed in description and notes. A tab is refused everywhere.
Bidirectional embeddings, overrides and isolatesU+202A to U+202E, U+2066 to U+2069
Zero-width charactersU+200B, U+200C, U+200D, U+2060, U+FEFF
Tag charactersU+E0000 to U+E007F
Private-use charactersU+E000 to U+F8FF, U+F0000 to U+FFFFD, U+100000 to U+10FFFD
The replacement characterU+FFFD (what is left of text that was damaged on the way, and of a lone surrogate escape in JSON)

The error names the field and the character, for example name: contains a character that is not allowed (U+200B). Letters in any script, accents, punctuation and emoji are fine; an emoji built with a zero-width joiner (U+200D) is not.

What couples see for each unit
unitShown as
per_event$14,500 per event
per_hour$14,500 per hour
per_person$14,500 per guest
starting_atFrom $14,500

That is amount_minor 1450000 in CAD. Cents are shown only when they are not zero ($45.50).

  • Validity dates are shown with the item ("Valid Jun 1, 2027 – Sep 30, 2027"). They are information for couples. The portal does not hide an item before or after its dates: remove it when it should stop showing.
  • Currency. A price list has one currency, and on the portal that is CAD. Every item names it; an item in any other currency is refused, in a sheet (items[1].currency) and by itself (currency).
  • Order. There is no position field. Items are shown in the order they have in the sheet. An item added later by itself goes to the end. Changing an existing item keeps its place. To reorder, send the whole sheet.

A price sheet

Fields of a price sheet
Field (JSON)TypeRequiredRules
itemsarray of itemsyes0 to 500 items. No two with the same sku, all in the same currency. An empty array clears the list on purpose; a missing items is refused.
notesstringnoUp to 500 characters, shown under the list (taxes, service charges). Replaced by every sheet: a sheet without notes removes them.
effective_atdate-timenoWhen your system issued the sheet. Informational only: it is not stored and schedules nothing. Prices go live when the sheet is received. A value more than 5 minutes in the future is refused, because scheduled sheets are not supported.

The three operations

The three operations
OperationEffect
Replace the sheetThe list becomes exactly the items you sent, in that order, with those notes. Items you left out are removed.
Upsert one itemCreates the item, or replaces every field of the item with that SKU. Fields you leave out are cleared, not kept. Notes and other items are untouched.
Remove one itemTakes that SKU off the list.

A price list holds at most 500 items. An upsert that would add a 501st SKU is refused; remove an item first or send a whole sheet. To publish next season's prices, send them when they should start to show.

HTTPS API

Base address: the Endpoint in your dashboard, currently https://vowportal-b2b.fly.dev/partner/v1.

  • Authentication. Every request carries the API key as Authorization: Bearer vpk_xxx…. The key identifies the business; no request names a vendor.
  • Requests. JSON, UTF-8, at most 1 MiB (1,048,576 bytes). Field names are snake_case and matched exactly. A body must be exactly one JSON object with no unknown fields, no field twice and every required field present (see the data model).
  • Responses. A change that was applied answers 200 with the list's new revision. Anything else is a problem document.
Answer to an applied change 200, JSON
{"revision_id":"rev_12"}

The machine-readable contract (OpenAPI 3.1, also covering webhooks) is partner-pricing.v1.yaml. Where it and this guide differ, this guide describes what the service does.

Replace the whole price sheet

PUT /partner/v1/price-sheet

Replace the price sheet curl
curl -X PUT https://vowportal-b2b.fly.dev/partner/v1/price-sheet \
  -H "Authorization: Bearer $PRICING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Prices include GST. A 15% service charge applies.",
    "items": [
      {
        "sku": "SAT-PEAK",
        "name": "Saturday, peak season",
        "description": "Whole venue for 10 hours, up to 180 guests.",
        "amount_minor": 1450000,
        "currency": "CAD",
        "unit": "per_event",
        "valid_from": "2027-06-01",
        "valid_until": "2027-09-30"
      },
      {
        "sku": "FRI-SUN",
        "name": "Friday or Sunday",
        "amount_minor": 980000,
        "currency": "CAD",
        "unit": "per_event"
      },
      {
        "sku": "BAR",
        "name": "Bar service",
        "amount_minor": 4500,
        "currency": "CAD",
        "unit": "per_person"
      }
    ]
  }'

Safe to send again: the same sheet leaves the same list. {"items": []} clears the list.

Create or replace one item

PUT /partner/v1/price-items/{sku}

Create or replace one item curl
curl -X PUT https://vowportal-b2b.fly.dev/partner/v1/price-items/SAT-PEAK \
  -H "Authorization: Bearer $PRICING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Saturday, peak season",
    "description": "Whole venue for 10 hours, up to 180 guests.",
    "amount_minor": 1525000,
    "currency": "CAD",
    "unit": "per_event",
    "valid_from": "2027-06-01",
    "valid_until": "2027-09-30"
  }'

The SKU in the URL is the item's (percent-encode it if it has characters a URL cannot carry). sku may be left out of the body. If it is there it must equal the one in the URL: a body that names another SKU is refused with 422, not overruled. Safe to send again.

Remove one item

DELETE /partner/v1/price-items/{sku}

Remove one item curl
curl -X DELETE https://vowportal-b2b.fly.dev/partner/v1/price-items/BAR \
  -H "Authorization: Bearer $PRICING_API_KEY"

No body. A SKU that is not in the list answers 404, and so does a second removal of the same SKU: treat 404 from a removal as "already gone".

Status codes

HTTPS API status codes
StatuscodeMeaningWhat to do
200Applied and live.
400invalid_requestThe body is not the JSON this endpoint takes: not UTF-8, malformed, empty, an unknown field, a field name in another case, a field twice, a wrong type (for example a decimal amount_minor).Fix the request. Do not retry unchanged.
401unauthenticatedNo key, a wrong key, a rotated key, or a disconnected connection. The answer carries WWW-Authenticate: Bearer realm="vowportal-pricing".Check the key. Do not retry unchanged.
404not_foundRemoval of a SKU that is not in the list, or a path that does not exist.For a removal, treat as done.
405method_not_allowedWrong method for this path.Fix the request.
413payload_too_largeThe body is larger than 1 MiB.Send less.
422validation_failedThe request was read and breaks a rule: a required field is missing, text is too long or not clean, the amount or the currency is out of bounds, the body's sku is not the URL's, the list would pass 500 items. errors[0].field names the field, for example items[1].currency.Fix the data. Do not retry unchanged.
429rate_limitedToo many requests.Wait Retry-After seconds, then retry.
500internal_errorOur fault. Whether the change was applied is not known.Retry up to three times with backoff, then stop and tell us: a request that fails this way every time will not start to work.
503service_unavailableThe price list is busy, or the gateway cannot reach its storage or did not hear back from it in time, or the request body arrived too slowly. Usually nothing was applied; after a timeout it may have been.Wait Retry-After seconds (5), then send it again: every operation is repeatable.

Every answer also carries Strict-Transport-Security and X-Content-Type-Options: nosniff.

Webhooks

For systems that can only send an outbound POST to a URL with a shared secret.

Endpoint. POST to the Webhook URL in your dashboard: https://vowportal-b2b.fly.dev/webhooks/pricing/{connection_id}, where the connection id looks like feed_0123456789abcdef01234567. The URL is not a secret; the signing secret is.

Fields of a webhook event
FieldTypeRequiredRules
event_idstringyesUnique per event, 1 to 128 characters, clean text (see the data model). A retry of the same event must reuse it.
event_typestringyesprice_sheet.published, price_item.upserted or price_item.removed.
occurred_atdate-timeyesRFC 3339, when the change happened in your system: 2026-10-10T09:30:00Z. Not more than 5 minutes in the future. Used for ordering.
dataobjectyesDepends on event_type, see below.

The body is one JSON object of at most 1 MiB (the size of the largest event, a whole price sheet), in UTF-8, with field names exact, no unknown fields and no field twice. The answer is 202 Accepted with an empty body once the event has been applied and recorded. 202 is also the answer for an event that was not applied because it was a duplicate or older than what the list already holds: in both cases there is nothing for you to do.

Event types

price_sheet.published: data is a price sheet. Replaces the list.

price_sheet.published JSON
{
  "event_id": "evt_20261010_0001",
  "event_type": "price_sheet.published",
  "occurred_at": "2026-10-10T09:30:00Z",
  "data": {
    "notes": "Prices include GST. A 15% service charge applies.",
    "items": [
      {
        "sku": "SAT-PEAK",
        "name": "Saturday, peak season",
        "amount_minor": 1450000,
        "currency": "CAD",
        "unit": "per_event"
      },
      {
        "sku": "BAR",
        "name": "Bar service",
        "amount_minor": 4500,
        "currency": "CAD",
        "unit": "per_person"
      }
    ]
  }
}

price_item.upserted: data is a price item, sku included. Creates or replaces that item.

price_item.upserted JSON
{
  "event_id": "evt_20261010_0002",
  "event_type": "price_item.upserted",
  "occurred_at": "2026-10-10T09:45:00Z",
  "data": {
    "sku": "SAT-PEAK",
    "name": "Saturday, peak season",
    "amount_minor": 1525000,
    "currency": "CAD",
    "unit": "per_event"
  }
}

price_item.removed: data is {"sku": "…"}. Removes that item. A SKU that is not in the list is accepted (202) and changes nothing.

price_item.removed JSON
{
  "event_id": "evt_20261010_0003",
  "event_type": "price_item.removed",
  "occurred_at": "2026-10-10T10:00:00Z",
  "data": { "sku": "BAR" }
}

Signing a delivery

Signature header on every delivery
X-Pricing-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
  • t is the time you signed, as Unix seconds (a decimal integer).
  • v1 is the HMAC-SHA256, in lowercase hexadecimal, of the bytes <t> + . + <raw body>: the digits of t, one full stop, then the request body exactly as it is sent, byte for byte.
  • The key of the HMAC is the whole signing secret as text, including the whsec_ prefix. Do not decode it.
  • The gateway accepts a signature whose t is within 5 minutes of its own clock, in either direction. Keep the sender's clock synchronised.
  • More than one v1= may be sent, separated by commas; one valid signature is enough. Parts other than t and v1 are ignored. The whole header value is at most 1,024 bytes, and a v1 is exactly 64 hexadecimal characters.
  • The header is looked at before the body. A delivery whose header is missing, malformed or outside the 5 minutes answers 401 without its body being read.

Sign the bytes you send. The usual mistake is to sign one serialisation of the JSON and send another (re-encoded, pretty-printed, with different key order or whitespace). Serialise once, sign that string, send that string.

A known answer to test a signing function with
InputValue
Secretwhsec_test_secret_do_not_use
t1791633600
Body{"event_id":"evt_1","event_type":"price_item.removed","occurred_at":"2026-10-10T10:00:00Z","data":{"sku":"BAR"}}
Header valuet=1791633600,v1=930ea6d232f2ac34fa68ceb20781c6e4a3752363dabdca52ececa7788d20fe6f
Sign and send in Node.js 18 or later, no dependencies
import { createHmac, randomUUID } from 'node:crypto';

const WEBHOOK_URL = process.env.PRICING_WEBHOOK_URL; // https://vowportal-b2b.fly.dev/webhooks/pricing/feed_...
const SECRET = process.env.PRICING_SIGNING_SECRET; // whsec_...

/** The X-Pricing-Signature value for these exact bytes. */
export function sign(secret, rawBody, t = Math.floor(Date.now() / 1000)) {
  const v1 = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  return `t=${t},v1=${v1}`;
}

export async function sendEvent(eventType, data, eventId = randomUUID(), occurredAt = new Date()) {
  // Serialise once, then sign and send the same string.
  const body = JSON.stringify({
    event_id: eventId,
    event_type: eventType,
    occurred_at: occurredAt.toISOString(),
    data
  });
  const res = await fetch(WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-Pricing-Signature': sign(SECRET, body) },
    body
  });
  return res.status; // 202 = accepted
}
Sign and send in Python 3.10 or later, standard library
import hashlib
import hmac
import json
import os
import time
import urllib.request
import uuid
from datetime import datetime, timezone

WEBHOOK_URL = os.environ["PRICING_WEBHOOK_URL"]  # https://vowportal-b2b.fly.dev/webhooks/pricing/feed_...
SECRET = os.environ["PRICING_SIGNING_SECRET"]  # whsec_...


def sign(secret: str, raw_body: bytes, t: int | None = None) -> str:
    """The X-Pricing-Signature value for these exact bytes."""
    t = int(time.time()) if t is None else t
    mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256)
    return f"t={t},v1={mac.hexdigest()}"


def send_event(event_type: str, data: dict, event_id: str | None = None) -> int:
    # Serialise once, then sign and send the same bytes.
    body = json.dumps({
        "event_id": event_id or str(uuid.uuid4()),
        "event_type": event_type,
        "occurred_at": datetime.now(timezone.utc).isoformat(),
        "data": data,
    }).encode()
    req = urllib.request.Request(WEBHOOK_URL, data=body, method="POST", headers={
        "Content-Type": "application/json",
        "X-Pricing-Signature": sign(SECRET, body),
    })
    with urllib.request.urlopen(req) as res:  # raises HTTPError on 4xx and 5xx
        return res.status  # 202 = accepted
Sign and send in Go standard library
package pricing

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"net/http"
	"strconv"
	"time"
)

// Sign returns the X-Pricing-Signature value for these exact bytes.
func Sign(secret string, rawBody []byte, t time.Time) string {
	ts := strconv.FormatInt(t.Unix(), 10)
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(ts + "."))
	mac.Write(rawBody)
	return "t=" + ts + ",v1=" + hex.EncodeToString(mac.Sum(nil))
}

// Send posts one event. rawBody is the JSON you serialised; it is signed and sent as is.
func Send(webhookURL, secret string, rawBody []byte) (int, error) {
	req, err := http.NewRequest(http.MethodPost, webhookURL, bytes.NewReader(rawBody))
	if err != nil {
		return 0, err
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Pricing-Signature", Sign(secret, rawBody, time.Now()))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return 0, err
	}
	defer res.Body.Close()
	return res.StatusCode, nil // 202 = accepted
}
Sign and send from a shell openssl and curl
BODY='{"event_id":"evt_test_1","event_type":"price_item.removed","occurred_at":"2026-10-10T10:00:00Z","data":{"sku":"BAR"}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$PRICING_SIGNING_SECRET" -r | cut -d' ' -f1)

curl -i -X POST "$PRICING_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Pricing-Signature: t=$T,v1=$SIG" \
  -d "$BODY"
# PRICING_WEBHOOK_URL is the address from your dashboard: https://vowportal-b2b.fly.dev/webhooks/pricing/feed_...

The shell example removes a SKU, so it is harmless: it answers 202 and, on a new connection, changes nothing.

Event ids, duplicates and order

  • Idempotent. An event is applied and its event_id recorded in one step. Sending the same event_id again changes nothing and answers 202. Event ids are remembered for at least 24 hours.
  • Retries. If a delivery fails with 429, 503 or no answer at all, send it again with the same event_id and the same body, as often as it takes; the event_id makes a repeat harmless. After a 500, retry up to three times and then stop and tell us. Never retry a 400 or 422: the same body fails the same way every time. Sign again when you retry, so t is fresh.
  • Ordered by occurred_at, last change wins. Each SKU remembers the time of the newest change applied to it. An event older than that is skipped for that SKU, so a late retry cannot put an old price back. Events with the same time are applied. Times are compared to the microsecond: two changes inside the same microsecond count as the same time.
  • Removals are remembered for 7 days. After that the gateway may forget when a SKU was removed. So an event whose occurred_at is more than 7 days old is skipped if it is a sheet, or if it is about a SKU that is not in the list. An event about a SKU that is in the list is compared with that SKU's newest change as usual, however old. After an outage longer than that, send a price_sheet.published with the whole list, dated now.
  • Sheets. A sheet older than the last sheet applied is skipped. Otherwise it replaces the list, except for SKUs that changed after the sheet's occurred_at: those keep their newer state, present or removed. An item event older than the last sheet is skipped unless that SKU changed after the sheet.
  • A skipped event still answers 202. The status tells you the delivery was handled, not that the list changed.

So occurred_at must be the time the change really happened, from one clock. Do not set it to the time of the retry.

Status codes

Webhook status codes
StatusMeaningWhat to do
202Handled: applied, a duplicate, or older than the list.Nothing.
400The body is not the JSON an event is (invalid_request): not UTF-8, malformed, an unknown field, a field name in another case, a field twice, a wrong type. It was not recorded.Fix the event. A retry of the same body fails again.
401The signature header is missing, malformed, older or newer than 5 minutes, or does not match; or the connection does not exist. All of these answer the same on purpose, with a problem document and WWW-Authenticate: Signature realm="vowportal-pricing-webhooks", header="X-Pricing-Signature".See Troubleshooting. Do not retry unchanged.
413Body larger than 1 MiB.Send less.
422The event was read and breaks a rule (validation_failed). Fields are named under data., for example data.items[0].unit or data.amount_minor. It was not recorded.Fix the event. A retry of the same body fails again.
429Too many deliveries.Wait Retry-After seconds, then retry with the same event_id.
500Our fault.Retry with the same event_id up to three times with backoff, then stop and tell us.
503Not applied yet. Also the answer when the body took more than 10 seconds to arrive after the headers, or when too many deliveries are being read at once.Wait Retry-After seconds (5), then retry with the same event_id.

The signature is checked before the body is read as an event, so a wrong signature answers 401 even when the JSON is also wrong. A header that is missing or malformed, or a signing time outside the 5 minutes, answers 401 before the body is read at all, whatever its size.

Rotating the signing secret

After Rotate secret the new secret works at once and the old one is accepted for 24 hours. Switch your system to the new secret within that time. Rotating again inside the 24 hours ends the first secret immediately.

Live pricing starts with the first event that puts a price in the list or replaces it. A price_item.removed on a new connection is accepted and does not start it.

gRPC

  • Address. The Endpoint in your dashboard, currently vowportal-b2b.fly.dev:8443. TLS is required (a public certificate; no client certificate). HTTP/2.
  • Contract. proto/vendorportal/pricing/v1/pricing.proto, which imports proto/vendorportal/common/v1/money.proto. Download both (below), then generate a client with protoc or buf. Server reflection is off in production, so tools such as grpcurl need the .proto files.
  • Authentication. Send the API key as metadata on every call. The key is lowercase authorization, the value Bearer vpk_xxx….
Get the .proto files shell
mkdir -p proto/vendorportal/pricing/v1 proto/vendorportal/common/v1
curl -fsS -o proto/vendorportal/pricing/v1/pricing.proto \
  https://vowportal.com/developers/pricing/contracts/proto/vendorportal/pricing/v1/pricing.proto
curl -fsS -o proto/vendorportal/common/v1/money.proto \
  https://vowportal.com/developers/pricing/contracts/proto/vendorportal/common/v1/money.proto

Or open them in a browser: pricing.proto, money.proto.

Methods of vendorportal.pricing.v1.PricingFeedService
MethodKindDoes
PublishPriceSheetunaryReplaces the whole sheet. Returns revision_id.
StreamPriceUpdatesclient streamingEach message is one upsert (a PriceItem) or one remove_sku (a string). Returns how many messages were accepted and the revision_id after the last one that changed the list.

The service is vendorportal.pricing.v1.PricingFeedService. There is no unary call for one item: open a stream, send one message, close it.

Differences from the JSON shapes:

  • The price is a message: price { currency_code: "CAD", amount_minor: 1450000 }. The message is required: an item without price is refused (items[0].price: is required). Protobuf cannot tell an amount_minor that was left out from 0, so with price set, an amount_minor of 0 (or none) is a price of zero: a free item. Leave nothing out that you mean to send.
  • unit is an enum: PRICE_UNIT_PER_EVENT, PRICE_UNIT_PER_HOUR, PRICE_UNIT_PER_PERSON, PRICE_UNIT_STARTING_AT. It must be set; PRICE_UNIT_UNSPECIFIED is refused.
  • valid_from and valid_until are timestamps. Only their calendar date in UTC is kept.
  • A PublishPriceSheetRequest with no items clears the list (protobuf cannot tell "no items" from "empty items").

Replace the whole price sheet

With grpcurl, from the folder that holds the proto/ folder. Against a local gateway (localhost:9090) add -plaintext.

PublishPriceSheet grpcurl
grpcurl \
  -import-path proto -proto vendorportal/pricing/v1/pricing.proto \
  -H "authorization: Bearer $PRICING_API_KEY" \
  -d '{
    "notes": "Prices include GST. A 15% service charge applies.",
    "items": [
      {
        "sku": "SAT-PEAK",
        "name": "Saturday, peak season",
        "price": { "currency_code": "CAD", "amount_minor": "1450000" },
        "unit": "PRICE_UNIT_PER_EVENT",
        "valid_from": "2027-06-01T00:00:00Z",
        "valid_until": "2027-09-30T00:00:00Z"
      },
      {
        "sku": "BAR",
        "name": "Bar service",
        "price": { "currency_code": "CAD", "amount_minor": "4500" },
        "unit": "PRICE_UNIT_PER_PERSON"
      }
    ]
  }' \
  vowportal-b2b.fly.dev:8443 \
  vendorportal.pricing.v1.PricingFeedService/PublishPriceSheet
PublishPriceSheet in Go grpc-go
package main

import (
	"context"
	"crypto/tls"
	"log"
	"os"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"

	// Generated from proto/ with protoc or buf; use your own import paths.
	commonv1 "example.com/yourapp/gen/vendorportal/common/v1"
	pricingv1 "example.com/yourapp/gen/vendorportal/pricing/v1"
)

func main() {
	conn, err := grpc.NewClient("vowportal-b2b.fly.dev:8443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{MinVersion: tls.VersionTLS12})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
	defer cancel()
	ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+os.Getenv("PRICING_API_KEY"))

	res, err := pricingv1.NewPricingFeedServiceClient(conn).PublishPriceSheet(ctx, &pricingv1.PublishPriceSheetRequest{
		Notes: "Prices include GST. A 15% service charge applies.",
		Items: []*pricingv1.PriceItem{{
			Sku:   "SAT-PEAK",
			Name:  "Saturday, peak season",
			Price: &commonv1.Money{CurrencyCode: "CAD", AmountMinor: 1450000},
			Unit:  pricingv1.PriceUnit_PRICE_UNIT_PER_EVENT,
		}},
	})
	if err != nil {
		log.Fatal(err) // status.Code(err) says why: see the error table
	}
	log.Println("live as", res.GetRevisionId())
}

Stream changes

StreamPriceUpdates grpcurl
grpcurl \
  -import-path proto -proto vendorportal/pricing/v1/pricing.proto \
  -H "authorization: Bearer $PRICING_API_KEY" \
  -d @ \
  vowportal-b2b.fly.dev:8443 \
  vendorportal.pricing.v1.PricingFeedService/StreamPriceUpdates <<'EOF'
{"upsert": {"sku": "SAT-PEAK", "name": "Saturday, peak season", "price": {"currency_code": "CAD", "amount_minor": "1525000"}, "unit": "PRICE_UNIT_PER_EVENT"}}
{"remove_sku": "BAR"}
EOF
Answer to a stream as grpcurl prints it
{
  "accepted": 2,
  "revisionId": "rev_14"
}
  • Each message is applied when it arrives, in order, as its own change. When the stream ends with an error, the messages before it stay applied.
  • A stream takes at most 10,000 messages. The next one ends it with RESOURCE_EXHAUSTED. Open a new stream for the rest.
  • A stream stays open at most 10 minutes, then ends with RESOURCE_EXHAUSTED whatever it is doing. At the rate limit 10,000 messages take under three minutes, so only a stream that sends slowly reaches this.
  • A stream may wait at most 30 seconds for its next message, its first included. A stream that sends nothing for that long ends with UNAVAILABLE. When a stream ends for any of these limits, the messages it sent before stay applied; the status message says how many.
  • Messages count against the connection's rate limit: opening the stream costs one call and covers the first 25 messages, and every further 25 messages cost one more call. A stream that outruns the limit ends with RESOURCE_EXHAUSTED and a retry-after trailer.
  • remove_sku for a SKU that is not in the list is accepted and does nothing (over the HTTPS API the same removal answers 404). Together with upserts being repeatable, this makes a stream safe to send again from its start.
  • A message with neither upsert nor remove_sku ends the stream with INVALID_ARGUMENT.
  • The API key is checked again with every message. Rotating the key or disconnecting ends an open stream with UNAUTHENTICATED.
  • Close the stream (half-close) to get the response. accepted counts every message taken, including removals that did nothing. revision_id is empty when no message changed the list.

What you can rely on

  • One message is at most 1.5 MiB (1,572,864 bytes), which every valid price sheet fits; a larger one is refused with RESOURCE_EXHAUSTED. Metadata is at most 16 KiB.
  • A call or a stream can end at any time with UNAVAILABLE. Your connection ends at our provider's edge, not at the gateway, and the gateway restarts on every release: it stops taking new calls, gives the ones in flight up to 15 seconds to finish, then closes what is left. Connections are also recycled from time to time. Treat UNAVAILABLE as routine: reconnect with backoff (standard gRPC clients do this by themselves for new calls) and send again. A sheet is repeatable, and a stream is safe to send again from its start; what the ended stream had sent stays applied.
  • Do not hold a stream open while there is nothing to send. Open one when prices change, send, close it and read the response. Set a deadline on every call. A stream left open with nothing to send ends after 30 seconds.
  • Apart from the stream limits above, do not rely on any particular idle time, connection lifetime, number of concurrent calls or keepalive interval: those are settled between the edge and the gateway and can change without notice.
  • Health: grpc.health.v1.Health/Check is served, needs no key, and reports the gateway as a whole whatever service name you send. It counts against the per-address rate limit. Watch and List answer UNIMPLEMENTED.

Status codes

gRPC status codes
gRPC statusMeaningWhat to do
OKApplied and live.
UNAUTHENTICATEDNo authorization metadata, not Bearer <key>, an unknown or rotated key, or a disconnected connection. A call without a key, or with a value that is not shaped like one, is refused before its message is read.Check the key. Do not retry unchanged.
INVALID_ARGUMENTA rule was broken. The message names the field: items[0].unit: must be per_event, per_hour, per_person or starting_at, or in a stream upsert.name: is required. Also: the list would pass 500 items.Fix the data. Do not retry unchanged.
RESOURCE_EXHAUSTEDRate limited (with a retry-after trailer, in whole seconds), the stream reached 10,000 messages or 10 minutes, or a message is larger than 1.5 MiB.Wait retry-after seconds, open a new stream, or send less.
UNAVAILABLEThe gateway could not complete the call: the price list is busy, its storage is out of reach or did not answer in time, or the gateway is restarting. Usually nothing was applied by that call or message; after a timeout it may have been.Reconnect and send again with backoff, starting at a few seconds. Every call is repeatable.
DEADLINE_EXCEEDED, CANCELLEDYour own deadline passed or you cancelled the call. The gateway never answers these for a delay of its own (that is UNAVAILABLE). The change may or may not have been applied.Send it again; sheets and upserts are repeatable.
UNIMPLEMENTEDA method the gateway does not serve (Health/Watch, Health/List, a misspelled method).Fix the call.
INTERNALOur fault. (Also what the gRPC library itself answers for a message that is not valid protobuf, such as a string that is not UTF-8; a generated client cannot send one.)Retry up to three times with backoff, then stop and tell us.

Errors

Over HTTPS every error is a problem document (RFC 9457) with Content-Type: application/problem+json.

A validation error HTTP response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "urn:vowportal:problem:validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "items[1].currency: must be CAD: prices on the portal are in Canadian dollars",
  "instance": "/partner/v1/price-sheet",
  "code": "validation_failed",
  "errors": [
    {
      "field": "items[1].currency",
      "code": "invalid",
      "message": "must be CAD: prices on the portal are in Canadian dollars"
    }
  ]
}
Members of a problem document
MemberMeaning
typeurn:vowportal:problem: followed by code.
titleA fixed short name for the code.
statusThe HTTP status, repeated.
detailWhat went wrong in this request, safe to log and to show a developer.
instanceThe path that was called.
codeThe stable machine-readable code. Branch on this, not on detail.
errorsOnly with validation_failed: the field at fault (field), code (always invalid) and message. One entry: validation stops at the first problem. Left out in the rare case that the rule is not about one field.
Error codes
codeStatusWhat to do
invalid_request400The body could not be read as the expected JSON. Fix it.
unauthenticated401Fix the credential or the signature. The answer names the scheme in WWW-Authenticate.
not_found404The SKU is not in the list, or the path is wrong.
method_not_allowed405Use the method documented for the path.
payload_too_large413Keep the body under 1 MiB.
validation_failed422A field broke a rule. Fix the field named in errors.
rate_limited429Wait Retry-After seconds.
internal_error500Retry up to three times with backoff, then stop and tell us.
service_unavailable503Wait Retry-After seconds (5), then retry.

Field names follow the request: items[2].currency in a sheet, sku or name for one item, data.items[2].currency in a webhook, upsert.name in a gRPC stream. A wrong JSON type is reported as invalid_request with the field in detail, for example Field "items.0.amount_minor" must be an integer. Over gRPC the same conditions arrive as status codes with the field in the status message.

Retry or fix?

  • Retry until it works: 429, 503 (RESOURCE_EXHAUSTED with a retry-after trailer, UNAVAILABLE), timeouts and connection errors. Wait for Retry-After when it is there and back off (for example 1 s, 2 s, 4 s, up to a minute, with some randomness) when it is not.
  • Retry a few times, then stop: 500 (INTERNAL). Three attempts with backoff, then alert a person and tell us. It is our fault, but a request that fails this way every time will not be fixed by sending it for ever.
  • Never retry unchanged: 400, 401, 404, 405, 413, 422 (INVALID_ARGUMENT, UNAUTHENTICATED, UNIMPLEMENTED). The same request gets the same answer. Bad data is always one of these, never a 500.

Limits and rate limits

Limits
LimitValue
Items in a price list500
sku64 characters
name120 characters
description500 characters
notes500 characters
event_id128 characters
amount_minor0 to 100,000,000 ($1,000,000.00)
currencyCAD only, one currency per list
HTTPS request body (API and webhooks)1 MiB. Enough for 500 items with every field full in Latin text; a sheet that fills every field to its limit in three- or four-byte characters (CJK, emoji) can pass 1 MiB and is refused with 413: send it over gRPC, or shorten the descriptions.
X-Pricing-Signature header1,024 bytes
gRPC message / metadata1.5 MiB (every valid sheet fits) / 16 KiB
Messages in one gRPC stream10,000
How long one gRPC stream stays open10 minutes, then RESOURCE_EXHAUSTED
Wait for the next message on a gRPC stream (the first included)30 seconds, then UNAVAILABLE
Time for a webhook body to arrive once its headers have10 seconds, then 503
Signature age5 minutes either way
effective_at, occurred_at in the futureat most 5 minutes
Wait for a busy price list5 seconds, then 503 / UNAVAILABLE
The gateway's own time limit for one change10 seconds, then 503 / UNAVAILABLE (never DEADLINE_EXCEEDED, which is only your own deadline)
Rate limits
What is countedLimit
Requests from one IP address (HTTPS and gRPC, the gRPC health check included, before any credential is looked up; an IPv6 address counts as its /64)240 a minute
Calls with one API key, HTTPS and gRPC together120 a minute
gRPC stream messages25 messages cost one call of the 120
Signed deliveries to one webhook240 a minute

Each limit is a burst that refills steadily. "120 a minute" means 120 at once, then two a second. For a stream that is 3,000 changes at once, then 50 a second.

Backing off over HTTPS. A refused request is 429 with Retry-After, the exact number of whole seconds until the next request will be accepted. Wait that long.

A rate-limited request HTTP response
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 1
RateLimit-Policy: 120;w=60
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 60

{
  "type": "urn:vowportal:problem:rate_limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "This connection is sending requests too fast. Retry after the time in Retry-After.",
  "instance": "/partner/v1/price-sheet",
  "code": "rate_limited"
}
Rate limit headers, sent on every counted response
HeaderMeaning
RateLimit-PolicyThe limit as <requests>;w=<window in seconds>: 120;w=60.
RateLimit-LimitThe most requests that can be made at once.
RateLimit-RemainingHow many more would be accepted right now.
RateLimit-ResetSeconds until the full allowance is back.

On an authenticated response these describe your connection's limit; on a 401 they describe the per-address limit. Use RateLimit-Remaining to slow down before you are refused.

Backing off over gRPC. RESOURCE_EXHAUSTED carries a retry-after trailer in whole seconds. There are no RateLimit-* values over gRPC.

Normal use is far below these numbers: a price list changes a few times a day. Send a sheet when prices change, not on a timer every few seconds.

Security

  • The credential is the identity. The gateway never accepts a vendor id, a slug or an account number. Whoever holds the key or the secret can change that business's public prices, and only that business's.
  • Shown once, not stored in the clear. API keys are stored only as a SHA-256 hash, so we cannot show a key again. Signing secrets are stored encrypted (AES-256-GCM), because checking a signature needs the secret. The dashboard shows the last four characters of either so you can tell which one is in use.
  • Treat it like a password. Keep it in a secret manager or an environment variable on a server. Not in source control, tickets, email, chat, screenshots or logs.
  • Never put a credential in a browser or a mobile app. Anything shipped to a device can be read by its user. Calls to the gateway come from a server.
  • Rotate when someone who had access leaves, when a provider changes, or when a credential may have been exposed. Rotating an API key cuts off the old key at once, including open gRPC streams. Rotating a signing secret leaves the old one valid for 24 hours.
  • Disconnect to revoke access completely.
  • Transport. Use the https:// address and, for gRPC, TLS. Do not disable certificate checks.
  • Replay. A signature is good for 5 minutes and an event id is applied once, so a captured delivery cannot be used to change prices later or twice.
  • Unknown connections. A webhook to a connection that does not exist answers exactly like a wrong signature, so connection ids cannot be probed.
  • What we log. Which connection changed what kind of thing and the new revision; for a gRPC stream, one line when it opens and one when it closes, with how many messages it took. Not the prices, not the names, and never a credential.
  • Nothing is read from a stranger. A gRPC call is refused before its message is read unless it carries a known key, and a webhook's body is read only after its signature header has the right shape and a signing time inside the window.

Testing and going live

There is no separate sandbox: the connection you create is the real one. Nothing is public until the first delivery is applied, so you can test authentication safely, and you can switch the profile back to the static list at any time.

Checklist for the first delivery

  1. The vendor has created the connection and passed on the credential and the address.
  2. The credential is stored on the server, not in code.
  3. Send the whole price sheet first. Every item in CAD with a unique sku, amounts in cents and present on every item.
  4. Expect 200 with a revision_id (HTTPS), 202 (webhook) or OK (gRPC).
  5. In the dashboard, the vendor presses Check connection: it should say the system is delivering prices and name the revision. The badge reads Connected and On your profile now: reads Live feed.
  6. Under Current prices from … the dashboard lists what was received. Check names, amounts, units, dates and order.
  7. Open the public page: the price list shows the new prices under "Live pricing from …".
  8. Change one item and remove one, and check again.
  9. Decide how you will notice a failure: alert on any answer other than success, and on no successful delivery for longer than you expect.

Do not start with an empty sheet. {"items": []} is a valid first delivery: it switches the profile to the live feed with no prices, and couples see "Pricing is shared on request."

To try a webhook signature before anything is live, send a price_item.removed for a SKU that does not exist: a correct signature answers 202 and changes nothing.

Troubleshooting

Troubleshooting
What you seeUsual causeFix
401 unauthenticated / UNAUTHENTICATED with an API keyThe header is not exactly "Authorization: Bearer <key>" (missing "Bearer ", quotes or a line break pasted with the key); the key was rotated; the connection was disconnected and connected again; a webhook connection's secret used as an API key.Compare the last four characters with API key in the dashboard. Rotate if in doubt.
401 on a webhook: "Missing, stale or invalid X-Pricing-Signature header."The signature was made over the parsed or re-serialised JSON, not the bytes sent; a proxy or library changed the body after signing; t is in milliseconds; the sender's clock is more than 5 minutes off; the secret was decoded or the whsec_ prefix dropped; the URL has another connection's id; the header name or the "t=…,v1=…" format is wrong; the old secret is still in use more than 24 hours after a rotation.Check your function against the known answer in the webhook section. Sign the exact body string. Sync the clock. Copy the URL from the dashboard again.
422 validation_failed / INVALID_ARGUMENTA field broke a rule.Read errors[0].field and message (or the gRPC status message): they name the field and the rule. Common ones: a currency other than CAD, a unit outside the four values, a duplicate SKU, valid_until before valid_from, a name over 120 characters.
422 "amount_minor: is required (send 0 for an item that is free)" / "price: is required…"The item has no amount (or null). A missing amount is never read as 0.Send amount_minor on every item; 0 for a free one. Over gRPC, set price.
422 "…contains a character that is not allowed (U+…)"The text holds a control, zero-width, bidirectional, tag or private-use character: often a tab, a byte order mark (U+FEFF) or a zero-width space (U+200B) pasted from a document, or U+0000 from a fixed-width export.Strip the character named in the message at the source. Line breaks are fine in description and notes.
422 "sku: must match the sku in the URL"The body of PUT /price-items/{sku} names another SKU than the URL.Leave sku out of the body, or send the same one.
422 "currency: must be CAD, the currency of the price list…"A change to one item in another currency than the rest of the list.Send the item in the list's currency.
400 invalid_requestNot UTF-8, malformed JSON, an unknown field, a field name in another case ("Name"), the same field twice, amount_minor as 14500.00 or "1450000", a date-time that is not RFC 3339, an empty body.Send UTF-8, integers for amounts, each documented field once in lowercase, YYYY-MM-DD dates.
422 "items: is required (send [] to clear the price list)"The sheet has no items field.Send items, even when empty.
422 "effective_at: is in the future…" or "occurred_at: is in the future"A scheduled sheet, or a fast clock.Send prices when they should show. Sync the clock.
422 "…the price list would hold more than 500 items…"The list is full.Remove items first, or send a whole sheet of at most 500.
The same delivery fails again and againIt is being retried after a 400 or 422, which never succeed unchanged.Retry only 429, 503 and connection errors without limit; 500 three times; everything else not at all.
404 on DELETEThe SKU is not in the list (already removed, or spelled differently: SKUs are case-sensitive).Treat as done, or check the SKU.
429 / RESOURCE_EXHAUSTEDToo many calls: a loop without a delay, one request per item instead of one sheet, or several jobs sharing a key.Wait Retry-After. Send a sheet, or a gRPC stream, instead of hundreds of single calls.
503 / UNAVAILABLE "The price list is busy."Two writers changed the same business's prices at once and one waited more than 5 seconds, or the gateway could not reach its storage.Retry after Retry-After. Send changes for one business one at a time.
Everything answers success, but couples do not see the prices"On your profile now:" reads "Static list": the vendor switched back to their own list, so deliveries are stored and not shown.The vendor opens Pricing, chooses Live feed and presses Use live pricing.
A webhook answers 202 but the list did not changeThe event was a duplicate event_id, or its occurred_at is older than the newest change to that SKU or than the last sheet, or more than 7 days old.Use a new event_id for a new change and the real time of the change.
An item lost its description or dates after an updateAn upsert replaces the whole item; fields left out are cleared.Send every field each time.
The notes under the list disappearedA sheet without notes removes them.Send notes with every sheet.
gRPC: "server does not support the reflection API"Reflection is off in production.Pass -import-path proto -proto vendorportal/pricing/v1/pricing.proto to grpcurl, or use a generated client.
gRPC: connection refused or a TLS errorWrong port, or plaintext against the TLS address.Use vowportal-b2b.fly.dev:8443 with TLS.
A gRPC call or stream ended with UNAVAILABLEThe gateway restarted for a release, a connection was recycled, or its storage was slow; or the stream sent nothing for 30 seconds.Routine: reconnect with backoff and send again. A stream is safe to send again from its start.
A long gRPC stream ended10,000 messages or 10 minutes (RESOURCE_EXHAUSTED), a rate limit (RESOURCE_EXHAUSTED with retry-after), 30 seconds without a message, a restart or a recycled connection (UNAVAILABLE), or a rotated key (UNAUTHENTICATED).Read the status code, then open a new stream and continue.
gRPC RESOURCE_EXHAUSTED "received message larger than max"One message over 1.5 MiB.No valid sheet is that large: check for padding or runaway text.

Glossary

Connection
The link between one business and one external system. It has an id (feed_…), a method, a source name and one credential.
Source name
The name of your system, typed when connecting. Shown to couples as "Live pricing from …".
API key
The credential for the HTTPS API and gRPC. Starts with vpk_.
Signing secret
The credential for webhooks. Starts with whsec_. Used to compute the signature; never sent itself.
Price sheet
The whole price list sent in one go, with optional notes.
Price item
One line of the list, identified by its SKU.
SKU
Your own stable identifier for an item.
Minor units
The smallest unit of a currency: cents for CAD. 1450000 is $14,500.00.
Revision
A counter (rev_1, rev_2, …) that goes up with every applied change.
Delivery
One request from your system that was accepted.
Static list / live feed
The two sources your profile's price list can show.
Upsert
Create the item if its SKU is new, replace it if it exists.
Idempotent
Safe to send again: a repeat has no further effect.

Getting help

Start with Troubleshooting. If you are still stuck, the vendor contacts the TL Portraitz team that verified the business. Include:

  • the connection's address or id (feed_…), and the method;
  • the time of the failing request, with the time zone;
  • the status code and the problem document (code, detail, instance), or the gRPC status and message;
  • the request body, if it has nothing confidential in it.

Never send the API key or the signing secret, to us or to anyone. If one has been pasted somewhere it should not be, rotate it.