openapi: 3.1.0 info: title: Vow Portal Partner Pricing API version: 0.2.0 description: | How a vendor's own system sends live prices to the portal. Served by services/b2b-gateway. There are three equivalent ways to send a price feed; pick whichever your system supports. All three have the same semantics and feed the same price list (docs/adr/0005): 1. **gRPC**: `vendorportal.pricing.v1.PricingFeedService` (proto/), API key as `authorization` metadata. 2. **HTTPS API** (this document, `/partner/v1/*`): API key as `Authorization: Bearer `. 3. **Webhooks** (this document, `/webhooks/pricing/{connection_id}`): for booking software that can only send outbound webhooks. Each delivery is signed with the connection's signing secret. Credentials come from the vendor dashboard (Pricing → Live feed). The credentials identify the vendor, so requests never name one. JSON is snake_case; money is integer minor units. **Request bodies.** UTF-8 JSON, exactly one object, at most 1 MiB. Member names are matched exactly (they are lowercase): an unknown member, one spelled in another case (`Name`) and one that appears twice are all refused with 400 `invalid_request`. A required member that is missing or `null` is refused with 422 `validation_failed`; nothing is filled in for it. In particular a price of zero must be sent as `"amount_minor": 0`. **Text.** `sku`, `name`, `description`, `notes` and `event_id` are refused (422), not cleaned, when they contain: a control character (U+0000 to U+001F, U+007F to U+009F; a line break, U+000A or U+000D, is allowed in `description` and `notes` only); a bidirectional embedding, override or isolate (U+202A to U+202E, U+2066 to U+2069); a zero-width character (U+200B, U+200C, U+200D, U+2060, U+FEFF); a tag character (U+E0000 to U+E007F); a private-use character (U+E000 to U+F8FF, U+F0000 to U+FFFFD, U+100000 to U+10FFFD); or the replacement character U+FFFD. **Errors.** Every error is an RFC 9457 problem document (`application/problem+json`, schema `Problem`). 400 means the body could not be read as what the endpoint takes; 422 means it was read and breaks a rule, and `errors` names the field. Neither is worth retrying unchanged. A path that does not exist answers 404 and a method a path does not take answers 405, both as problem documents (`components.responses.NotFound` and `MethodNotAllowed`). 500 is a fault of the gateway: retry it a few times with backoff, then stop and report it. Every response carries `Strict-Transport-Security` and `X-Content-Type-Options: nosniff`. servers: - url: https://vowportal-b2b.fly.dev description: Production - url: http://localhost:9091 description: Local b2b-gateway (`make dev-b2b`) security: - apiKey: [] paths: /partner/v1/price-sheet: put: operationId: publishPriceSheet summary: Replace the whole price sheet description: >- Items not included are removed. Safe to retry: sending the same sheet again leaves the same price list. requestBody: required: true content: application/json: schema: { $ref: "#/components/schemas/PriceSheet" } responses: "200": description: Accepted and live content: application/json: schema: { $ref: "#/components/schemas/Revision" } "400": { $ref: "#/components/responses/InvalidRequest" } "401": { $ref: "#/components/responses/Unauthenticated" } "413": { $ref: "#/components/responses/PayloadTooLarge" } "422": { $ref: "#/components/responses/ValidationFailed" } "429": { $ref: "#/components/responses/RateLimited" } "500": { $ref: "#/components/responses/InternalError" } "503": { $ref: "#/components/responses/Unavailable" } /partner/v1/price-items/{sku}: parameters: - { name: sku, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 64 } } put: operationId: upsertPriceItem summary: Create or replace one item description: >- The SKU in the path is the item's: the path wins. `sku` may be left out of the body; a body `sku` that differs from the path is refused (422), not overruled. A price list holds at most 500 items and one currency. Adding a new SKU to a full list is refused (422); remove an item first or replace the whole sheet. Safe to retry: sending the same item again leaves the same price list. requestBody: required: true content: application/json: schema: { $ref: "#/components/schemas/PriceItemBody" } responses: "200": description: Accepted and live content: application/json: schema: { $ref: "#/components/schemas/Revision" } "400": { $ref: "#/components/responses/InvalidRequest" } "401": { $ref: "#/components/responses/Unauthenticated" } "413": { $ref: "#/components/responses/PayloadTooLarge" } "422": { $ref: "#/components/responses/ValidationFailed" } "429": { $ref: "#/components/responses/RateLimited" } "500": { $ref: "#/components/responses/InternalError" } "503": { $ref: "#/components/responses/Unavailable" } delete: operationId: removePriceItem summary: Remove one item description: A SKU that is not in the price list answers 404, so does a repeated removal. responses: "200": description: Removed content: application/json: schema: { $ref: "#/components/schemas/Revision" } "401": { $ref: "#/components/responses/Unauthenticated" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationFailed" } "429": { $ref: "#/components/responses/RateLimited" } "500": { $ref: "#/components/responses/InternalError" } "503": { $ref: "#/components/responses/Unavailable" } /webhooks/pricing/{connection_id}: post: operationId: receivePricingWebhook summary: Receive a signed pricing event description: | Configure this URL and the signing secret in your booking software. Sign each delivery like this: `X-Pricing-Signature: t=,v1=.">`. Deliveries more than 5 minutes old are rejected. Retries must reuse the same `event_id`: an event is recorded only once it has been applied, so a retry after a 5xx is applied and a retry after a 202 is ignored. Events older than the newest change already applied to a SKU don't overwrite it (ordering by `occurred_at`), and an item event older than the last applied price sheet is ignored unless that SKU has changed since: the sheet already replaced the whole list. A price list holds at most 500 items; an event that would add a new SKU to a full list is rejected (422) and not recorded. A `price_item.removed` for a SKU that is not in the list is accepted (202) and changes nothing that is shown; live pricing starts with the first event that puts a price in the list or replaces it. After a secret rotation, the previous secret is accepted for 24 hours. The signature header is looked at before the body: a request whose header is missing, malformed or outside the 5 minutes answers 401 without its body being read. security: [] parameters: - { name: connection_id, in: path, required: true, schema: { type: string, pattern: "^feed_[0-9A-Za-z]{1,64}$" } } - name: X-Pricing-Signature in: header required: true schema: { type: string, maxLength: 1024, example: "t=1790918000,v1=5257a869e7..." } requestBody: required: true content: application/json: schema: { $ref: "#/components/schemas/PricingEvent" } responses: "202": { description: Accepted (also returned for a duplicate event_id). The body is empty. } "400": { $ref: "#/components/responses/InvalidRequest" } "401": { $ref: "#/components/responses/WebhookUnauthenticated" } "413": { $ref: "#/components/responses/PayloadTooLarge" } "422": { $ref: "#/components/responses/ValidationFailed" } "429": { $ref: "#/components/responses/RateLimited" } "500": { $ref: "#/components/responses/InternalError" } "503": { $ref: "#/components/responses/Unavailable" } components: securitySchemes: apiKey: type: http scheme: bearer description: The feed connection's API key from the vendor dashboard (prefix `vpk_`). responses: InvalidRequest: description: | The body could not be read as what the endpoint takes: not UTF-8, not JSON, empty, a member of the wrong type, an unknown member, a member name in another case, or a member that appears twice. `code` is `invalid_request`. content: application/problem+json: schema: { $ref: "#/components/schemas/Problem" } ValidationFailed: description: | The request was read and breaks a rule. `code` is `validation_failed`; `errors` names the field, except when the rule is not about one field. content: application/problem+json: schema: { $ref: "#/components/schemas/Problem" } Unauthenticated: description: No API key, a value that is not one, or a key that is unknown, rotated or disconnected. headers: WWW-Authenticate: { schema: { type: string }, description: '`Bearer realm="vowportal-pricing"`' } content: application/problem+json: schema: { $ref: "#/components/schemas/Problem" } WebhookUnauthenticated: description: >- Missing, malformed, stale or wrong signature, or an unknown connection. These are indistinguishable on purpose: the status, the headers and the body are the same. headers: WWW-Authenticate: schema: { type: string } description: '`Signature realm="vowportal-pricing-webhooks", header="X-Pricing-Signature"`' content: application/problem+json: schema: { $ref: "#/components/schemas/Problem" } NotFound: description: >- The SKU is not in the price list (a removal), or no endpoint has this path. content: application/problem+json: schema: { $ref: "#/components/schemas/Problem" } MethodNotAllowed: description: The path exists and does not take this method. content: application/problem+json: schema: { $ref: "#/components/schemas/Problem" } PayloadTooLarge: description: The request body is larger than 1 MiB (1,048,576 bytes). content: application/problem+json: schema: { $ref: "#/components/schemas/Problem" } InternalError: description: >- A fault of the gateway. Whether the change was applied is not known. Retry a few times with backoff (every operation is repeatable), then stop and report it: the same request failing every time will not start to work. content: application/problem+json: schema: { $ref: "#/components/schemas/Problem" } Unavailable: description: | The gateway could not complete the request right now: the price list is busy, its storage is unreachable or did not answer in time, or live pricing is not set up. Usually nothing was applied; after a timeout it may have been. Retry after the time in `Retry-After`: every operation is repeatable. headers: Retry-After: { schema: { type: integer, minimum: 1 }, description: Seconds to wait before retrying } content: application/problem+json: schema: { $ref: "#/components/schemas/Problem" } RateLimited: description: | Too many requests. `Retry-After` is the exact number of seconds until the next request will be accepted. Every limited operation also sends the `RateLimit-*` headers on its successful responses, so a client can pace itself before it is refused. headers: Retry-After: { schema: { type: integer, minimum: 1 }, description: Seconds to wait before retrying } RateLimit-Limit: { schema: { type: integer }, description: The most requests that can be made at once } RateLimit-Remaining: { schema: { type: integer }, description: Requests that would be accepted right now } RateLimit-Reset: { schema: { type: integer }, description: Seconds until the full allowance is back } RateLimit-Policy: { schema: { type: string }, description: 'The limit as `;w=`, e.g. `120;w=60`' } content: application/problem+json: schema: { $ref: "#/components/schemas/Problem" } schemas: PriceUnit: type: string enum: [per_event, per_hour, per_person, starting_at] PriceItemBody: description: >- A price item as the body of `PUT /partner/v1/price-items/{sku}`, where `sku` is optional because the path carries it. No other members are accepted. type: object required: [name, amount_minor, currency, unit] additionalProperties: false properties: sku: { type: string, minLength: 1, maxLength: 64 } name: { type: string, minLength: 1, maxLength: 120 } description: { type: string, maxLength: 500 } amount_minor: type: integer format: int64 minimum: 0 maximum: 100000000 description: >- The price in minor units (cents). Required: a missing or null value is refused, never read as 0. 0 is a valid price (an item that is free or included). currency: type: string pattern: "^[A-Z]{3}$" enum: [CAD] description: ISO 4217. The portal lists prices in Canadian dollars; no other currency is accepted. unit: { $ref: "#/components/schemas/PriceUnit" } valid_from: { type: string, format: date } valid_until: { type: string, format: date } PriceItem: description: A price item in a sheet or a webhook event, where `sku` is required. allOf: - { $ref: "#/components/schemas/PriceItemBody" } - { type: object, required: [sku] } PriceSheet: type: object required: [items] additionalProperties: false properties: items: type: array maxItems: 500 description: Every item in the same currency, no two with the same `sku`. items: { $ref: "#/components/schemas/PriceItem" } effective_at: type: string format: date-time description: >- When the vendor's system issued the sheet. Optional and informational only: it is not stored and changes nothing about how the sheet is applied. Prices go live when the sheet is received. The one rule is that scheduled sheets are not supported, so a time more than 5 minutes in the future is rejected (422); any other value, or none, is accepted. Send next season's prices when they should start to show, or use each item's valid_from / valid_until. notes: { type: string, maxLength: 500 } Revision: type: object required: [revision_id] properties: revision_id: { type: string } RemovedItem: type: object required: [sku] additionalProperties: false properties: sku: { type: string, minLength: 1, maxLength: 64 } PricingEvent: type: object required: [event_id, event_type, occurred_at, data] additionalProperties: false properties: event_id: { type: string, minLength: 1, maxLength: 128, description: "Unique per event; reuse it on retries" } event_type: type: string enum: [price_sheet.published, price_item.upserted, price_item.removed] occurred_at: { type: string, format: date-time } data: description: | price_sheet.published → PriceSheet; price_item.upserted → PriceItem; price_item.removed → RemovedItem oneOf: - { $ref: "#/components/schemas/PriceSheet" } - { $ref: "#/components/schemas/PriceItem" } - { $ref: "#/components/schemas/RemovedItem" } FieldError: type: object required: [field, code, message] additionalProperties: false properties: field: { type: string, description: "The request member at fault, e.g. `items[2].currency` or `data.sku`" } code: { type: string, enum: [invalid] } message: { type: string } Problem: description: RFC 9457 problem details. type: object required: [type, title, status, code] additionalProperties: false properties: type: { type: string, pattern: "^urn:vowportal:problem:[a-z_]+$", description: "`urn:vowportal:problem:` followed by `code`" } title: { type: string } status: { type: integer, minimum: 400, maximum: 599 } detail: { type: string } instance: { type: string, description: The path that was called } code: type: string description: The stable machine-readable code. Branch on this. enum: - invalid_request - validation_failed - unauthenticated - not_found - method_not_allowed - payload_too_large - rate_limited - internal_error - service_unavailable errors: type: array description: Only with `validation_failed`, and at most one entry (validation stops at the first problem). maxItems: 1 items: { $ref: "#/components/schemas/FieldError" }