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 |
|---|---|
| You, the vendor | Create 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 provider | Builds 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 again | Press 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.
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.
| Your system… | Use | It needs |
|---|---|---|
| can call an HTTPS API (most custom or in-house systems, scripts, scheduled jobs) | HTTPS API | An 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) | Webhook | A 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 connection | gRPC | An 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
- Open Pricing in the vendor dashboard.
- Under Price source, choose Live feed.
- In Connect your booking system, answer How will your system send prices? with gRPC, HTTPS API or Webhook.
- 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.
- 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:
| Method | Address |
|---|---|
| HTTPS API | https://vowportal-b2b.fly.dev/partner/v1 |
| Webhook | https://vowportal-b2b.fly.dev/webhooks/pricing/feed_… (ends with your connection's id) |
| gRPC | vowportal-b2b.fly.dev:8443 (TLS) |
Connection states
| Badge | Meaning |
|---|---|
| Waiting for the first prices | The connection exists and nothing has been delivered. Your profile still shows your static list. |
| Connected | At least one delivery has been applied. Last sync says when the latest one arrived, Revision which one
it was (rev_1, rev_2, …). |
| Stale, Disconnected | Reserved. 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
| Field (JSON) | Type | Required | Rules |
|---|---|---|---|
sku | string | yes | Your 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. |
name | string | yes | 1 to 120 characters. What couples read, for example "Saturday, peak season". |
description | string | no | Up to 500 characters. |
amount_minor | integer | yes | The 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. |
currency | string | yes | CAD. The portal lists prices in Canadian dollars; no other currency is
accepted. |
unit | string | yes | One of per_event, per_hour, per_person, starting_at. |
valid_from | date | no | YYYY-MM-DD. |
valid_until | date | no | YYYY-MM-DD. Not before valid_from. |
Lengths count characters, not bytes.
- Required means required. A required field that is missing
or
nullis refused (422); nothing is filled in for it. A price of zero is a real price, so it has to be sent as0. Over gRPC, where a number that was left out cannot be told from 0, it is thepricemessage 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,notesand a webhook'sevent_idare 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.
| Kind | Code points |
|---|---|
| Control characters | U+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 isolates | U+202A to U+202E, U+2066 to U+2069 |
| Zero-width characters | U+200B, U+200C, U+200D, U+2060, U+FEFF |
| Tag characters | U+E0000 to U+E007F |
| Private-use characters | U+E000 to U+F8FF, U+F0000 to U+FFFFD, U+100000 to U+10FFFD |
| The replacement character | U+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.
unit | Shown as |
|---|---|
per_event | $14,500 per event |
per_hour | $14,500 per hour |
per_person | $14,500 per guest |
starting_at | From $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
| Field (JSON) | Type | Required | Rules |
|---|---|---|---|
items | array of items | yes | 0 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. |
notes | string | no | Up to 500 characters, shown under the list (taxes, service charges). Replaced by every
sheet: a sheet without notes removes them. |
effective_at | date-time | no | When 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
| Operation | Effect |
|---|---|
| Replace the sheet | The list becomes exactly the items you sent, in that order, with those notes. Items you left out are removed. |
| Upsert one item | Creates 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 item | Takes 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
200with the list's new revision. Anything else is a problem document.
{"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
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}
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}
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
| Status | code | Meaning | What to do |
|---|---|---|---|
| 200 | Applied and live. | ||
| 400 | invalid_request | The 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. |
| 401 | unauthenticated | No 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. |
| 404 | not_found | Removal of a SKU that is not in the list, or a path that does not exist. | For a removal, treat as done. |
| 405 | method_not_allowed | Wrong method for this path. | Fix the request. |
| 413 | payload_too_large | The body is larger than 1 MiB. | Send less. |
| 422 | validation_failed | The 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. |
| 429 | rate_limited | Too many requests. | Wait Retry-After seconds, then retry. |
| 500 | internal_error | Our 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. |
| 503 | service_unavailable | The 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.
| Field | Type | Required | Rules |
|---|---|---|---|
event_id | string | yes | Unique per event, 1 to 128 characters, clean text (see the data model). A retry of the same event must reuse it. |
event_type | string | yes | price_sheet.published, price_item.upserted or price_item.removed. |
occurred_at | date-time | yes | RFC 3339, when the change happened in your system: 2026-10-10T09:30:00Z. Not
more than 5 minutes in the future. Used for ordering. |
data | object | yes | Depends 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.
{
"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.
{
"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.
{
"event_id": "evt_20261010_0003",
"event_type": "price_item.removed",
"occurred_at": "2026-10-10T10:00:00Z",
"data": { "sku": "BAR" }
}Signing a delivery
X-Pricing-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">tis the time you signed, as Unix seconds (a decimal integer).v1is the HMAC-SHA256, in lowercase hexadecimal, of the bytes<t>+.+<raw body>: the digits oft, 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
tis 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 thantandv1are ignored. The whole header value is at most 1,024 bytes, and av1is 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
401without 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.
| Input | Value |
|---|---|
| Secret | whsec_test_secret_do_not_use |
t | 1791633600 |
| Body | {"event_id":"evt_1","event_type":"price_item.removed","occurred_at":"2026-10-10T10:00:00Z","data":{"sku":"BAR"}} |
| Header value | t=1791633600,v1=930ea6d232f2ac34fa68ceb20781c6e4a3752363dabdca52ececa7788d20fe6f |
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
}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 = acceptedpackage 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
}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_idrecorded in one step. Sending the sameevent_idagain changes nothing and answers202. Event ids are remembered for at least 24 hours. - Retries. If a delivery fails with
429,503or no answer at all, send it again with the sameevent_idand the same body, as often as it takes; theevent_idmakes a repeat harmless. After a500, retry up to three times and then stop and tell us. Never retry a400or422: the same body fails the same way every time. Sign again when you retry, sotis 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_atis 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 aprice_sheet.publishedwith 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
| Status | Meaning | What to do |
|---|---|---|
| 202 | Handled: applied, a duplicate, or older than the list. | Nothing. |
| 400 | The 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. |
| 401 | The 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. |
| 413 | Body larger than 1 MiB. | Send less. |
| 422 | The 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. |
| 429 | Too many deliveries. | Wait Retry-After seconds, then retry with the same event_id. |
| 500 | Our fault. | Retry with the same event_id up to three times with backoff, then stop and tell
us. |
| 503 | Not 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 importsproto/vendorportal/common/v1/money.proto. Download both (below), then generate a client withprotocorbuf. Server reflection is off in production, so tools such asgrpcurlneed the.protofiles. - Authentication. Send the API key as metadata on every
call. The key is lowercase
authorization, the valueBearer vpk_xxx….
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.protoOr open them in a browser: pricing.proto, money.proto.
| Method | Kind | Does |
|---|---|---|
PublishPriceSheet | unary | Replaces the whole sheet. Returns revision_id. |
StreamPriceUpdates | client streaming | Each 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 withoutpriceis refused (items[0].price: is required). Protobuf cannot tell anamount_minorthat was left out from 0, so withpriceset, anamount_minorof 0 (or none) is a price of zero: a free item. Leave nothing out that you mean to send. unitis an enum:PRICE_UNIT_PER_EVENT,PRICE_UNIT_PER_HOUR,PRICE_UNIT_PER_PERSON,PRICE_UNIT_STARTING_AT. It must be set;PRICE_UNIT_UNSPECIFIEDis refused.valid_fromandvalid_untilare timestamps. Only their calendar date in UTC is kept.- A
PublishPriceSheetRequestwith 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.
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/PublishPriceSheetpackage 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
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{
"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_EXHAUSTEDwhatever 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_EXHAUSTEDand aretry-aftertrailer. remove_skufor a SKU that is not in the list is accepted and does nothing (over the HTTPS API the same removal answers404). Together with upserts being repeatable, this makes a stream safe to send again from its start.- A message with neither
upsertnorremove_skuends the stream withINVALID_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.
acceptedcounts every message taken, including removals that did nothing.revision_idis 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. TreatUNAVAILABLEas 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/Checkis served, needs no key, and reports the gateway as a whole whatever service name you send. It counts against the per-address rate limit.WatchandListanswerUNIMPLEMENTED.
Status codes
| gRPC status | Meaning | What to do |
|---|---|---|
OK | Applied and live. | |
UNAUTHENTICATED | No 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_ARGUMENT | A 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_EXHAUSTED | Rate 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. |
UNAVAILABLE | The 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, CANCELLED | Your 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. |
UNIMPLEMENTED | A method the gateway does not serve (Health/Watch, Health/List,
a misspelled method). | Fix the call. |
INTERNAL | Our 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.
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"
}
]
}| Member | Meaning |
|---|---|
type | urn:vowportal:problem: followed by code. |
title | A fixed short name for the code. |
status | The HTTP status, repeated. |
detail | What went wrong in this request, safe to log and to show a developer. |
instance | The path that was called. |
code | The stable machine-readable code. Branch on this, not on detail. |
errors | Only 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. |
code | Status | What to do |
|---|---|---|
invalid_request | 400 | The body could not be read as the expected JSON. Fix it. |
unauthenticated | 401 | Fix the credential or the signature. The answer names the scheme in WWW-Authenticate. |
not_found | 404 | The SKU is not in the list, or the path is wrong. |
method_not_allowed | 405 | Use the method documented for the path. |
payload_too_large | 413 | Keep the body under 1 MiB. |
validation_failed | 422 | A field broke a rule. Fix the field named in errors. |
rate_limited | 429 | Wait Retry-After seconds. |
internal_error | 500 | Retry up to three times with backoff, then stop and tell us. |
service_unavailable | 503 | Wait 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_EXHAUSTEDwith aretry-aftertrailer,UNAVAILABLE), timeouts and connection errors. Wait forRetry-Afterwhen 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 a500.
Limits and rate limits
| Limit | Value |
|---|---|
| Items in a price list | 500 |
| sku | 64 characters |
| name | 120 characters |
| description | 500 characters |
| notes | 500 characters |
| event_id | 128 characters |
| amount_minor | 0 to 100,000,000 ($1,000,000.00) |
| currency | CAD 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 header | 1,024 bytes |
| gRPC message / metadata | 1.5 MiB (every valid sheet fits) / 16 KiB |
| Messages in one gRPC stream | 10,000 |
| How long one gRPC stream stays open | 10 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 have | 10 seconds, then 503 |
| Signature age | 5 minutes either way |
| effective_at, occurred_at in the future | at most 5 minutes |
| Wait for a busy price list | 5 seconds, then 503 / UNAVAILABLE |
| The gateway's own time limit for one change | 10 seconds, then 503 / UNAVAILABLE (never DEADLINE_EXCEEDED, which is only your own deadline) |
| What is counted | Limit |
|---|---|
| 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 together | 120 a minute |
| gRPC stream messages | 25 messages cost one call of the 120 |
| Signed deliveries to one webhook | 240 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.
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"
}| Header | Meaning |
|---|---|
RateLimit-Policy | The limit as <requests>;w=<window in seconds>: 120;w=60. |
RateLimit-Limit | The most requests that can be made at once. |
RateLimit-Remaining | How many more would be accepted right now. |
RateLimit-Reset | Seconds 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
- The vendor has created the connection and passed on the credential and the address.
- The credential is stored on the server, not in code.
- Send the whole price sheet first. Every item in
CADwith a uniquesku, amounts in cents and present on every item. - Expect
200with arevision_id(HTTPS),202(webhook) orOK(gRPC). - 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.
- Under Current prices from … the dashboard lists what was received. Check names, amounts, units, dates and order.
- Open the public page: the price list shows the new prices under "Live pricing from …".
- Change one item and remove one, and check again.
- 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
| What you see | Usual cause | Fix |
|---|---|---|
| 401 unauthenticated / UNAUTHENTICATED with an API key | The 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_ARGUMENT | A 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_request | Not 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 again | It 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 DELETE | The SKU is not in the list (already removed, or spelled differently: SKUs are case-sensitive). | Treat as done, or check the SKU. |
| 429 / RESOURCE_EXHAUSTED | Too 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 change | The 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 update | An upsert replaces the whole item; fields left out are cleared. | Send every field each time. |
| The notes under the list disappeared | A 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 error | Wrong port, or plaintext against the TLS address. | Use vowportal-b2b.fly.dev:8443 with TLS. |
| A gRPC call or stream ended with UNAVAILABLE | The 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 ended | 10,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.