repull 0.2.42 → 0.2.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. checksums.yaml +4 -4
  2. data/lib/repull/api/airbnb_api.rb +2 -2
  3. data/lib/repull/api/listings_api.rb +146 -6
  4. data/lib/repull/api/reservations_api.rb +93 -0
  5. data/lib/repull/models/account_disconnected_payload.rb +3 -2
  6. data/lib/repull/models/get_listing_markups200_response.rb +15 -4
  7. data/lib/repull/models/get_listing_markups200_response_vrbo_inner.rb +181 -0
  8. data/lib/repull/models/get_reservation_summary200_response.rb +353 -0
  9. data/lib/repull/models/get_reservation_summary200_response_totals_inner.rb +478 -0
  10. data/lib/repull/models/get_vrbo_publish_job200_response.rb +199 -0
  11. data/lib/repull/models/get_vrbo_publish_job200_response_job.rb +300 -0
  12. data/lib/repull/models/get_vrbo_publish_job200_response_job_rejected_photos_inner.rb +157 -0
  13. data/lib/repull/models/map_connect_booking_rooms_response.rb +44 -5
  14. data/lib/repull/models/message.rb +29 -5
  15. data/lib/repull/models/message_actor.rb +159 -0
  16. data/lib/repull/models/message_reaction.rb +178 -0
  17. data/lib/repull/models/publish_listing_to_vrbo_request.rb +158 -0
  18. data/lib/repull/models/reservation.rb +12 -1
  19. data/lib/repull/models/reservation_message_reaction_event.rb +281 -0
  20. data/lib/repull/models/reservation_message_reaction_payload.rb +225 -0
  21. data/lib/repull/models/reservation_message_reaction_payload_reaction.rb +175 -0
  22. data/lib/repull/models/reservation_message_read_event.rb +281 -0
  23. data/lib/repull/models/reservation_message_read_payload.rb +227 -0
  24. data/lib/repull/models/reservation_message_updated_payload.rb +1 -1
  25. data/lib/repull/models/set_listing_markup_request.rb +16 -6
  26. data/lib/repull/models/update_airbnb_message_request.rb +1 -1
  27. data/lib/repull/models/webhook_event.rb +4 -0
  28. data/lib/repull/models/webhook_event_type.rb +3 -1
  29. data/lib/repull/version.rb +1 -1
  30. data/lib/repull.rb +14 -0
  31. data/openapi/v1.json +1055 -14
  32. data/scripts/regen.sh +1 -1
  33. metadata +16 -2
data/openapi/v1.json CHANGED
@@ -757,6 +757,12 @@
757
757
  "type": "string",
758
758
  "description": "Internal Repull listing ID this reservation is on."
759
759
  },
760
+ "listingName": {
761
+ "type": "string",
762
+ "nullable": true,
763
+ "description": "Name of the listing this reservation is on, so a report or message can name it without a second lookup.",
764
+ "example": "Lakeside Cabin"
765
+ },
760
766
  "guestId": {
761
767
  "type": "string",
762
768
  "deprecated": true,
@@ -1556,7 +1562,61 @@
1556
1562
  "readAt": {
1557
1563
  "type": "string",
1558
1564
  "format": "date-time",
1559
- "nullable": true
1565
+ "nullable": true,
1566
+ "description": "Who read it depends on `direction`. **Outbound** (your message): when the guest first read it, from the channel's read receipts \u2014 Airbnb reports them; on other channels it stays `null`. Changes are sent as `reservation.message.read`. **Inbound** (the guest's message): when your team answered it or marked it handled."
1567
+ },
1568
+ "hostReadAt": {
1569
+ "type": "string",
1570
+ "format": "date-time",
1571
+ "nullable": true,
1572
+ "description": "Inbound messages only: when the host or a co-host first read it on the channel, from the channel's read receipts (Airbnb reports them). `null` for your own messages, on other channels, and until your side has opened the conversation since it arrived."
1573
+ },
1574
+ "reactions": {
1575
+ "type": "array",
1576
+ "description": "Reactions on this message, oldest first. Airbnb reports them; empty on other channels. Added and removed reactions are sent as `reservation.message.reaction`. To react, `PATCH /v1/channels/airbnb/messaging/{threadId}/messages/{messageId}` with `action: \"react\"`.",
1577
+ "items": {
1578
+ "$ref": "#/components/schemas/MessageReaction"
1579
+ }
1580
+ }
1581
+ }
1582
+ },
1583
+ "MessageReaction": {
1584
+ "type": "object",
1585
+ "description": "One reaction on a message.",
1586
+ "properties": {
1587
+ "id": {
1588
+ "type": "string",
1589
+ "description": "The channel's id for this reaction.",
1590
+ "example": "9e0b945a-b03d-4e28-ad48-5f7fc706a67f"
1591
+ },
1592
+ "emoji": {
1593
+ "type": "string",
1594
+ "example": "\u2764\ufe0f"
1595
+ },
1596
+ "by": {
1597
+ "$ref": "#/components/schemas/MessageActor"
1598
+ },
1599
+ "at": {
1600
+ "type": "string",
1601
+ "format": "date-time",
1602
+ "nullable": true,
1603
+ "description": "When it was added, as the channel reports it."
1604
+ }
1605
+ }
1606
+ },
1607
+ "MessageActor": {
1608
+ "type": "object",
1609
+ "description": "Who did something on a message.",
1610
+ "properties": {
1611
+ "type": {
1612
+ "type": "string",
1613
+ "example": "guest",
1614
+ "description": "`guest`, `cotraveler`, `booker`, `host` or `cohost`. `unknown` when the channel did not say."
1615
+ },
1616
+ "name": {
1617
+ "type": "string",
1618
+ "nullable": true,
1619
+ "example": "Maya"
1560
1620
  }
1561
1621
  }
1562
1622
  },
@@ -2893,6 +2953,8 @@
2893
2953
  "reservation.message.received",
2894
2954
  "reservation.message.sent",
2895
2955
  "reservation.message.updated",
2956
+ "reservation.message.read",
2957
+ "reservation.message.reaction",
2896
2958
  "reservation.alteration.created",
2897
2959
  "reservation.alteration.responded",
2898
2960
  "reservation.request.created",
@@ -3218,7 +3280,7 @@
3218
3280
  },
3219
3281
  "ReservationMessageUpdatedPayload": {
3220
3282
  "type": "object",
3221
- "description": "Payload for `reservation.message.updated`: a message was edited on the channel. `body` is the new text; `previousBody` what it replaced. Read receipts and reactions do not fire it.",
3283
+ "description": "Payload for `reservation.message.updated`: a message was edited on the channel. `body` is the new text; `previousBody` what it replaced. Read receipts and reactions do not fire it: they have their own events, `reservation.message.read` and `reservation.message.reaction`.",
3222
3284
  "properties": {
3223
3285
  "hotelId": {
3224
3286
  "type": "string",
@@ -3284,6 +3346,117 @@
3284
3346
  }
3285
3347
  }
3286
3348
  },
3349
+ "ReservationMessageReadPayload": {
3350
+ "type": "object",
3351
+ "description": "Payload for `reservation.message.read`: the guest read the conversation up to and including `messageId`, a message from your side. Every earlier message in it was read by then too. Airbnb reports read receipts; other channels do not fire this event.",
3352
+ "properties": {
3353
+ "reservationId": {
3354
+ "type": "integer",
3355
+ "nullable": true,
3356
+ "example": 235970
3357
+ },
3358
+ "threadId": {
3359
+ "type": "string",
3360
+ "example": "900301",
3361
+ "description": "The conversation id (`GET /v1/conversations/{id}`)."
3362
+ },
3363
+ "externalThreadId": {
3364
+ "type": "string",
3365
+ "nullable": true,
3366
+ "example": "2648057088"
3367
+ },
3368
+ "listingId": {
3369
+ "type": "integer",
3370
+ "nullable": true,
3371
+ "example": 23893
3372
+ },
3373
+ "channel": {
3374
+ "type": "string",
3375
+ "example": "airbnb"
3376
+ },
3377
+ "messageId": {
3378
+ "type": "string",
3379
+ "example": "1854462",
3380
+ "description": "The newest message the guest has read. Its `readAt` is now set."
3381
+ },
3382
+ "externalMessageId": {
3383
+ "type": "string",
3384
+ "nullable": true,
3385
+ "example": "33532605539"
3386
+ },
3387
+ "readAt": {
3388
+ "type": "string",
3389
+ "format": "date-time",
3390
+ "description": "When the guest read it, as the channel reports it."
3391
+ },
3392
+ "reader": {
3393
+ "$ref": "#/components/schemas/MessageActor"
3394
+ }
3395
+ }
3396
+ },
3397
+ "ReservationMessageReactionPayload": {
3398
+ "type": "object",
3399
+ "description": "Payload for `reservation.message.reaction`: someone on the conversation added or removed a reaction. Airbnb reports reactions; other channels do not fire this event.",
3400
+ "properties": {
3401
+ "reservationId": {
3402
+ "type": "integer",
3403
+ "nullable": true,
3404
+ "example": 235970
3405
+ },
3406
+ "threadId": {
3407
+ "type": "string",
3408
+ "example": "900301"
3409
+ },
3410
+ "externalThreadId": {
3411
+ "type": "string",
3412
+ "nullable": true,
3413
+ "example": "2648057088"
3414
+ },
3415
+ "listingId": {
3416
+ "type": "integer",
3417
+ "nullable": true,
3418
+ "example": 23893
3419
+ },
3420
+ "channel": {
3421
+ "type": "string",
3422
+ "example": "airbnb"
3423
+ },
3424
+ "messageId": {
3425
+ "type": "string",
3426
+ "example": "1854462",
3427
+ "description": "The message reacted to."
3428
+ },
3429
+ "externalMessageId": {
3430
+ "type": "string",
3431
+ "nullable": true,
3432
+ "example": "33532605539"
3433
+ },
3434
+ "action": {
3435
+ "type": "string"
3436
+ },
3437
+ "reaction": {
3438
+ "type": "object",
3439
+ "properties": {
3440
+ "id": {
3441
+ "type": "string",
3442
+ "example": "9e0b945a-b03d-4e28-ad48-5f7fc706a67f"
3443
+ },
3444
+ "emoji": {
3445
+ "type": "string",
3446
+ "example": "\u2764\ufe0f"
3447
+ },
3448
+ "by": {
3449
+ "$ref": "#/components/schemas/MessageActor"
3450
+ },
3451
+ "at": {
3452
+ "type": "string",
3453
+ "format": "date-time",
3454
+ "description": "When it was added; for `removed`, when Repull saw it go."
3455
+ }
3456
+ }
3457
+ }
3458
+ }
3459
+ },
3287
3460
  "AlterationWebhookObject": {
3288
3461
  "type": "object",
3289
3462
  "description": "Lightweight alteration snapshot delivered as `data.object` on `reservation.alteration.*` events. Currently Airbnb only. Fetch full state (original vs new dates/guests/price) via `GET /v1/channels/airbnb/alterations` filtered by `reservation_code`.",
@@ -4035,7 +4208,7 @@
4035
4208
  },
4036
4209
  "AccountDisconnectedPayload": {
4037
4210
  "type": "object",
4038
- "description": "Payload for `account.disconnected`. A PMS or channel connection was revoked, expired, or rejected by the upstream provider.",
4211
+ "description": "Payload for `account.disconnected`. A PMS or channel connection was revoked, expired, or rejected by the upstream provider. Sent for Airbnb, Booking.com Extranet logins, Vrbo logins and PMS connections (Hostaway, Guesty, Smoobu, Lodgify, Beds24, Hospitable, OwnerRez, iGMS, BookingSync, Track, Mews, Cloudbeds, Zeevou, RentalReady, CiiRUS, \u2026). A PMS connection is reported when the PMS refuses its credentials (API key revoked or invalid, 401/403, token refresh refused); timeouts, rate limits and 5xx errors are retried and never reported. Sent once per disconnect, not on every failed sync. When the connection works again \u2014 credentials fixed in the PMS, or reconnected \u2014 Repull re-imports the changes made while it was down and sends their `reservation.*` events, so nothing missed has to be fetched by hand.",
4039
4212
  "properties": {
4040
4213
  "workspaceId": {
4041
4214
  "type": "string",
@@ -4053,7 +4226,8 @@
4053
4226
  },
4054
4227
  "provider": {
4055
4228
  "type": "string",
4056
- "example": "airbnb"
4229
+ "example": "airbnb",
4230
+ "description": "Channel or PMS id: `airbnb`, `booking_extranet`, `vrbo`, or the PMS (`hostaway`, `guesty`, `smoobu`, \u2026)."
4057
4231
  },
4058
4232
  "disconnectedAt": {
4059
4233
  "type": "string",
@@ -4063,7 +4237,7 @@
4063
4237
  "reason": {
4064
4238
  "type": "string",
4065
4239
  "example": "refresh_token_rejected",
4066
- "description": "Why the connection was lost. `refresh_token_rejected` \u2014 upstream OAuth refresh endpoint returned a hard rejection. `manual_disconnect` \u2014 host/admin disconnected via the dashboard. `auth_expired` \u2014 credentials aged out without ever being used. `revoked_upstream` \u2014 provider notified us the user revoked access."
4240
+ "description": "Why the connection was lost. `refresh_token_rejected` \u2014 upstream OAuth refresh endpoint returned a hard rejection. `manual_disconnect` \u2014 host/admin disconnected via the dashboard. `auth_expired` \u2014 the saved credentials stopped working: an Extranet or Vrbo login was signed out, or a PMS rejected its API key or token (401/403). `revoked_upstream` \u2014 provider notified us the user revoked access."
4067
4241
  },
4068
4242
  "listings": {
4069
4243
  "type": "array",
@@ -4729,6 +4903,78 @@
4729
4903
  }
4730
4904
  }
4731
4905
  },
4906
+ "ReservationMessageReadEvent": {
4907
+ "type": "object",
4908
+ "required": [
4909
+ "event",
4910
+ "eventId",
4911
+ "apiVersion",
4912
+ "timestamp",
4913
+ "data"
4914
+ ],
4915
+ "properties": {
4916
+ "event": {
4917
+ "type": "string",
4918
+ "description": "The event name. This field is `event`, not `type`."
4919
+ },
4920
+ "eventId": {
4921
+ "type": "string",
4922
+ "format": "uuid",
4923
+ "description": "Stable across every delivery and replay of this logical event \u2014 dedupe on it."
4924
+ },
4925
+ "apiVersion": {
4926
+ "type": "string",
4927
+ "example": "2026-04"
4928
+ },
4929
+ "timestamp": {
4930
+ "type": "string",
4931
+ "format": "date-time",
4932
+ "description": "When this delivery was built."
4933
+ },
4934
+ "account": {
4935
+ "$ref": "#/components/schemas/WebhookEventAccount"
4936
+ },
4937
+ "data": {
4938
+ "$ref": "#/components/schemas/ReservationMessageReadPayload"
4939
+ }
4940
+ }
4941
+ },
4942
+ "ReservationMessageReactionEvent": {
4943
+ "type": "object",
4944
+ "required": [
4945
+ "event",
4946
+ "eventId",
4947
+ "apiVersion",
4948
+ "timestamp",
4949
+ "data"
4950
+ ],
4951
+ "properties": {
4952
+ "event": {
4953
+ "type": "string",
4954
+ "description": "The event name. This field is `event`, not `type`."
4955
+ },
4956
+ "eventId": {
4957
+ "type": "string",
4958
+ "format": "uuid",
4959
+ "description": "Stable across every delivery and replay of this logical event \u2014 dedupe on it."
4960
+ },
4961
+ "apiVersion": {
4962
+ "type": "string",
4963
+ "example": "2026-04"
4964
+ },
4965
+ "timestamp": {
4966
+ "type": "string",
4967
+ "format": "date-time",
4968
+ "description": "When this delivery was built."
4969
+ },
4970
+ "account": {
4971
+ "$ref": "#/components/schemas/WebhookEventAccount"
4972
+ },
4973
+ "data": {
4974
+ "$ref": "#/components/schemas/ReservationMessageReactionPayload"
4975
+ }
4976
+ }
4977
+ },
4732
4978
  "ReservationAlterationCreatedEvent": {
4733
4979
  "type": "object",
4734
4980
  "required": [
@@ -6341,6 +6587,12 @@
6341
6587
  {
6342
6588
  "$ref": "#/components/schemas/ReservationMessageUpdatedEvent"
6343
6589
  },
6590
+ {
6591
+ "$ref": "#/components/schemas/ReservationMessageReadEvent"
6592
+ },
6593
+ {
6594
+ "$ref": "#/components/schemas/ReservationMessageReactionEvent"
6595
+ },
6344
6596
  {
6345
6597
  "$ref": "#/components/schemas/ReservationAlterationCreatedEvent"
6346
6598
  },
@@ -6447,6 +6699,8 @@
6447
6699
  "reservation.message.received": "#/components/schemas/ReservationMessageReceivedEvent",
6448
6700
  "reservation.message.sent": "#/components/schemas/ReservationMessageSentEvent",
6449
6701
  "reservation.message.updated": "#/components/schemas/ReservationMessageUpdatedEvent",
6702
+ "reservation.message.read": "#/components/schemas/ReservationMessageReadEvent",
6703
+ "reservation.message.reaction": "#/components/schemas/ReservationMessageReactionEvent",
6450
6704
  "reservation.alteration.created": "#/components/schemas/ReservationAlterationCreatedEvent",
6451
6705
  "reservation.alteration.responded": "#/components/schemas/ReservationAlterationRespondedEvent",
6452
6706
  "reservation.request.created": "#/components/schemas/ReservationRequestCreatedEvent",
@@ -15393,13 +15647,25 @@
15393
15647
  "type": "integer",
15394
15648
  "nullable": true,
15395
15649
  "description": "How many reservations Booking.com returned for the property. Equal to `reservationsImported` unless some could not be attached to a listing \u2014 so `0` here means Booking.com had none. `null` when the sync could not run."
15650
+ },
15651
+ "needsCalendar": {
15652
+ "type": "array",
15653
+ "items": {
15654
+ "type": "string"
15655
+ },
15656
+ "description": "Ids of the listings this call created from Booking.com rooms (`create: true`). They start without a calendar: Booking.com shows those rooms closed and nothing is sent to Booking.com for them until they have one. Give a listing a calendar by setting its prices and availability with `PUT /v1/availability/{propertyId}`, or by mapping the same home from Airbnb so its calendar is used. Rooms mapped to an existing listing are not listed: that listing's calendar is pushed as before."
15657
+ },
15658
+ "calendarNote": {
15659
+ "type": "string",
15660
+ "description": "Plain-language explanation of `needsCalendar`, present only when it is non-empty."
15396
15661
  }
15397
15662
  },
15398
15663
  "required": [
15399
15664
  "success",
15400
15665
  "mapped",
15401
15666
  "sessionId",
15402
- "connectionId"
15667
+ "connectionId",
15668
+ "needsCalendar"
15403
15669
  ]
15404
15670
  },
15405
15671
  "MapAirbnbListingRequest": {
@@ -24305,7 +24571,7 @@
24305
24571
  "patch": {
24306
24572
  "operationId": "update_airbnb_message",
24307
24573
  "summary": "Edit / react to / mark an Airbnb message",
24308
- "description": "Act on a single message in an Airbnb thread. **Write-side** \u2014 calls Airbnb upstream. The `action` discriminator selects the operation:\n\n- `edit` \u2014 replace message text (requires `message`).\n- `unsend` \u2014 retract the message.\n- `read` \u2014 mark the message as read.\n- `react` \u2014 add a reaction (requires `reaction`).\n\nRequires a connected Airbnb host, else `404 no_connection`.\n\nReturns `403 listing_inactive` when the listing this resolves to is inactive. An inactive listing keeps syncing, but cannot be read or changed through the API until it is activated.",
24574
+ "description": "Act on a single message in an Airbnb thread. **Write-side** \u2014 calls Airbnb upstream. The `action` discriminator selects the operation:\n\n- `edit` \u2014 replace message text (requires `message`).\n- `unsend` \u2014 retract the message.\n- `read` \u2014 mark the message as read on Airbnb, as the host. Airbnb accepts it (it has been used in production); whether and when the guest sees it as read is up to Airbnb and is not confirmed yet. Your side's read state on each guest message is `hostReadAt` on `GET /v1/conversations/{id}/messages`.\n- `react` \u2014 add a reaction (requires `reaction`, e.g. `\"\ud83d\udc4d\"`). Airbnb decides which reactions it accepts: a refusal is `422 reaction_not_supported` naming the field, with Airbnb's reason. Removing a reaction is not available yet.\n\nReactions and read receipts from the guest's side arrive on each message (`reactions`, `readAt`) and as the `reservation.message.reaction` and `reservation.message.read` webhooks.\n\nRequires a connected Airbnb host, else `404 no_connection`.\n\nReturns `403 listing_inactive` when the listing this resolves to is inactive. An inactive listing keeps syncing, but cannot be read or changed through the API until it is activated.",
24309
24575
  "tags": [
24310
24576
  "Airbnb"
24311
24577
  ],
@@ -24355,7 +24621,7 @@
24355
24621
  },
24356
24622
  "reaction": {
24357
24623
  "type": "string",
24358
- "description": "Reaction to add. Required when `action` is `react`."
24624
+ "description": "Reaction to add, e.g. `\ud83d\udc4d`. Required when `action` is `react`. At most 32 characters; Airbnb decides which reactions it accepts."
24359
24625
  }
24360
24626
  }
24361
24627
  }
@@ -26825,7 +27091,7 @@
26825
27091
  "put": {
26826
27092
  "operationId": "updateListingContent",
26827
27093
  "summary": "Update canonical listing content",
26828
- "description": "Write your PMS's canonical listing content \u2014 title, description, amenities, address, occupancy, and policies \u2014 into a Repull listing, making it the source of truth. This is the flagship \"the PMS owns listing content, Repull distributes it\" enabler.\n\n**Listings managed in a connected PMS** (Guesty, Hostaway, \u2026): the PMS owns their content, so title, descriptions, check-in/out times, capacity, amenities, house rules, address and added photos are written to the PMS first; Repull keeps only what it accepted (refused sections are in `deferred`, its per-section outcome in `pms`). A section that PMS cannot write returns `422 pms_write_unsupported` naming it when nothing was applied (or is listed in `deferred` when other sections were); `GET /v1/listings/{id}` \u2192 `capabilities.pms.listings` says which sections it takes. A PMS whose connector writes no listing content at all (Mews, Cloudbeds, Lodgify, \u2026) keeps today's behaviour: the content is written to Repull only. Send photos with `photosMode: \"append\"` \u2014 replacing a PMS listing's photo set needs the PMS's own photo ids. A revoked PMS connection is `403 connection_reauth_required`.\n\n**Partial update:** every field is optional. Only the fields you send are written; absent fields are left untouched. `amenities` is a FULL replacement of the amenity set (omit to leave untouched, send `[]` to clear).\n\n**Multilingual:** send `locale` to say which language this copy is in (`it`, `pt-BR`, \u2026). Canonical content is stored per locale, so each language keeps its own row instead of overwriting the English one. Omit it for English.\n\n**Local write only \u2014 NOT a channel publish.** This mutates Repull's own copy of the content. It does NOT push to Airbnb / Booking.com; it marks the channels dirty so a later publish knows what changed. Distribution stays a separate explicit step.\n\n**Photos are deferred:** a provided `photos` array is echoed back in the `deferred` field and NOT persisted (media ingestion is a follow-up).\n\nCross-tenant access (a listing that belongs to a different workspace) returns 404 \u2014 never 403. This endpoint is served even when the account is over the plan-listings cap, since editing content on a listing you already own never grows the portfolio.\n\nReturns `403 listing_inactive` when the listing is inactive. An inactive listing keeps syncing, but cannot be read or changed through the API until it is activated.",
27094
+ "description": "Write your PMS's canonical listing content \u2014 title, description, amenities, address, occupancy, and policies \u2014 into a Repull listing, making it the source of truth. This is the flagship \"the PMS owns listing content, Repull distributes it\" enabler.\n\n**Listings managed in a connected PMS** (Guesty, Hostaway, \u2026): the PMS owns their content, so title, descriptions, check-in/out times, capacity, amenities, house rules, address and added photos are written to the PMS first; Repull keeps only what it accepted (refused sections are in `deferred`, its per-section outcome in `pms`). A section that PMS cannot write returns `422 pms_write_unsupported` naming it when nothing was applied (or is listed in `deferred` when other sections were); `GET /v1/listings/{id}` \u2192 `capabilities.pms.listings` says which sections it takes. A PMS whose connector writes no listing content at all (Mews, Cloudbeds, Lodgify, \u2026) keeps today's behaviour: the content is written to Repull only. Send photos with `photosMode: \"append\"` \u2014 replacing a PMS listing's photo set needs the PMS's own photo ids. A revoked PMS connection is `403 connection_reauth_required`.\n\n**Partial update:** every field is optional. Only the fields you send are written; absent fields are left untouched. `amenities` is a FULL replacement of the amenity set (omit to leave untouched, send `[]` to clear).\n\n**Multilingual:** send `locale` to say which language this copy is in (`it`, `pt-BR`, \u2026). Canonical content is stored per locale, so each language keeps its own row instead of overwriting the English one. Omit it for English.\n\n**Local write only \u2014 NOT a channel publish.** This mutates Repull's own copy of the content. It does NOT push to Airbnb / Booking.com; it marks the channels dirty so a later publish knows what changed. Distribution stays a separate explicit step.\n\n**Photos:** `photos` is a list of hosted image URLs (or structured refs) saved to the listing in order: a full replacement by default, or added after the existing ones with `photosMode: \"append\"`. A publish sends them to the channels. An array with no valid http(s) URL is reported in `deferred` and the existing photos are left alone.\n\nCross-tenant access (a listing that belongs to a different workspace) returns 404 \u2014 never 403. This endpoint is served even when the account is over the plan-listings cap, since editing content on a listing you already own never grows the portfolio.\n\nReturns `403 listing_inactive` when the listing is inactive. An inactive listing keeps syncing, but cannot be read or changed through the API until it is activated.",
26829
27095
  "tags": [
26830
27096
  "Listings"
26831
27097
  ],
@@ -35980,7 +36246,7 @@
35980
36246
  "get": {
35981
36247
  "operationId": "get_listing_markups",
35982
36248
  "summary": "Get a listing's channel markups",
35983
- "description": "The markup each channel adds to this listing's price.\n\nA listing's price on a channel is its own nightly price plus the channel's markup: a $200 night with a 35% Airbnb markup is sent to Airbnb as $270. The calendar keeps the listing's own price (`GET /v1/availability/{propertyId}` returns it); the markup is added only when a price is sent to the channel.\n\n- **Airbnb** \u2014 one markup per listing.\n- **Booking.com** \u2014 one markup per **property**, shared by every listing priced through it (`listingIds` names them).\n\nReturns `404 not_found` for a listing that does not exist or is not in this workspace, and `403 listing_inactive` for an inactive one.",
36249
+ "description": "The markup each channel adds to this listing's price.\n\nA listing's price on a channel is its own nightly price plus the channel's markup: a $200 night with a 35% Airbnb markup is sent to Airbnb as $270. The calendar keeps the listing's own price (`GET /v1/availability/{propertyId}` returns it); the markup is added only when a price is sent to the channel.\n\n- **Airbnb** \u2014 one markup per listing.\n- **Booking.com** \u2014 one markup per **property**, shared by every listing priced through it (`listingIds` names them).\n- **Vrbo** \u2014 one markup per connected **Vrbo account**, shared by every listing linked on it (`listingIds` names them). Prices reach Vrbo through its calendar queue.\n\nReturns `404 not_found` for a listing that does not exist or is not in this workspace, and `403 listing_inactive` for an inactive one.",
35984
36250
  "tags": [
35985
36251
  "Listings"
35986
36252
  ],
@@ -36049,6 +36315,35 @@
36049
36315
  }
36050
36316
  }
36051
36317
  }
36318
+ },
36319
+ "vrbo": {
36320
+ "type": "array",
36321
+ "items": {
36322
+ "type": "object",
36323
+ "properties": {
36324
+ "accountId": {
36325
+ "type": "string",
36326
+ "description": "The Vrbo account, as its connection id (`vrbo:13`)."
36327
+ },
36328
+ "vrboListingNumber": {
36329
+ "type": "string",
36330
+ "description": "The Vrbo listing number this listing is linked to."
36331
+ },
36332
+ "markupPercent": {
36333
+ "type": "number",
36334
+ "nullable": true,
36335
+ "description": "Percent added on Vrbo, for every listing linked on this account.",
36336
+ "example": 20
36337
+ },
36338
+ "listingIds": {
36339
+ "type": "array",
36340
+ "items": {
36341
+ "type": "string"
36342
+ },
36343
+ "description": "Listings in this workspace linked on this Vrbo account \u2014 all share this markup."
36344
+ }
36345
+ }
36346
+ }
36052
36347
  }
36053
36348
  }
36054
36349
  }
@@ -36069,7 +36364,7 @@
36069
36364
  "put": {
36070
36365
  "operationId": "set_listing_markup",
36071
36366
  "summary": "Set a listing's markup on a channel",
36072
- "description": "Set the markup one channel adds to this listing's price. When the value changes, the affected listings' prices are re-sent to that channel straight away (`pricesResent`); nothing else is sent.\n\nA listing's price on a channel is its own nightly price plus the channel's markup: a $200 night with a 35% Airbnb markup is sent to Airbnb as $270. The calendar keeps the listing's own price (`GET /v1/availability/{propertyId}` returns it); the markup is added only when a price is sent to the channel.\n\n- **Airbnb** \u2014 one markup per listing.\n- **Booking.com** \u2014 one markup per **property**, shared by every listing priced through it (`listingIds` names them).\n\nReturns `404 not_found` for a listing that does not exist or is not in this workspace, and `403 listing_inactive` for an inactive one.\n\nOn Booking.com the markup belongs to the property, so setting it reprices every listing on that property (`affectedListingIds`). A listing on more than one property must name one with `hotelId`; without it the request is refused with `409 ambiguous_booking_mapping` listing the candidates, rather than repricing a property it guessed.\n\n`markupPercent` is a percentage \u2014 `15` for 15%. A value between 0 and 1 is refused as a probable fraction, with the number to send instead.",
36367
+ "description": "Set the markup one channel adds to this listing's price. When the value changes, the affected listings' prices are re-sent to that channel straight away (`pricesResent`); nothing else is sent.\n\nA listing's price on a channel is its own nightly price plus the channel's markup: a $200 night with a 35% Airbnb markup is sent to Airbnb as $270. The calendar keeps the listing's own price (`GET /v1/availability/{propertyId}` returns it); the markup is added only when a price is sent to the channel.\n\n- **Airbnb** \u2014 one markup per listing.\n- **Booking.com** \u2014 one markup per **property**, shared by every listing priced through it (`listingIds` names them).\n- **Vrbo** \u2014 one markup per connected **Vrbo account**, shared by every listing linked on it (`listingIds` names them). Prices reach Vrbo through its calendar queue.\n\nReturns `404 not_found` for a listing that does not exist or is not in this workspace, and `403 listing_inactive` for an inactive one.\n\nOn Booking.com the markup belongs to the property, so setting it reprices every listing on that property (`affectedListingIds`). A listing on more than one property must name one with `hotelId`; without it the request is refused with `409 ambiguous_booking_mapping` listing the candidates, rather than repricing a property it guessed.\n\nOn Vrbo the markup belongs to the connected Vrbo account, so setting it reprices every listing linked on that account (`affectedListingIds`). A listing linked on more than one account names one with `accountId`, else `409 ambiguous_vrbo_account`; a listing not linked to Vrbo is `409 listing_not_on_vrbo`.\n\n`markupPercent` is a percentage \u2014 `15` for 15%. A value between 0 and 1 is refused as a probable fraction, with the number to send instead.",
36073
36368
  "tags": [
36074
36369
  "Listings"
36075
36370
  ],
@@ -36099,7 +36394,8 @@
36099
36394
  "type": "string",
36100
36395
  "enum": [
36101
36396
  "airbnb",
36102
- "booking"
36397
+ "booking",
36398
+ "vrbo"
36103
36399
  ]
36104
36400
  },
36105
36401
  "markupPercent": {
@@ -36113,6 +36409,10 @@
36113
36409
  "hotelId": {
36114
36410
  "type": "string",
36115
36411
  "description": "Booking.com property \u2014 required when the listing is on more than one."
36412
+ },
36413
+ "accountId": {
36414
+ "type": "string",
36415
+ "description": "Vrbo account (`vrbo:13`) \u2014 required when the listing is linked on more than one."
36116
36416
  }
36117
36417
  }
36118
36418
  },
@@ -36125,7 +36425,7 @@
36125
36425
  },
36126
36426
  "responses": {
36127
36427
  "200": {
36128
- "description": "Saved. `{ id, channel, markupPercent, changed, hotelId?, affectedListingIds, pricesResent }`."
36428
+ "description": "Saved. `{ id, channel, markupPercent, changed, hotelId? | accountId?, affectedListingIds, pricesResent }`."
36129
36429
  },
36130
36430
  "401": {
36131
36431
  "$ref": "#/components/responses/Unauthorized"
@@ -36137,7 +36437,7 @@
36137
36437
  "$ref": "#/components/responses/NotFound"
36138
36438
  },
36139
36439
  "409": {
36140
- "description": "`ambiguous_booking_mapping` \u2014 the listing is on several Booking.com properties; `valid_values` lists them."
36440
+ "description": "`ambiguous_booking_mapping` \u2014 the listing is on several Booking.com properties; `valid_values` lists them. `ambiguous_vrbo_account` \u2014 the same for Vrbo accounts. `listing_not_on_vrbo` \u2014 `channel: \"vrbo\"` on a listing with no Vrbo unit linked."
36141
36441
  },
36142
36442
  "422": {
36143
36443
  "$ref": "#/components/responses/UnprocessableEntity"
@@ -41675,6 +41975,747 @@
41675
41975
  }
41676
41976
  }
41677
41977
  }
41978
+ },
41979
+ "/v1/listings/{id}/publish/vrbo": {
41980
+ "post": {
41981
+ "operationId": "publishListingToVrbo",
41982
+ "summary": "Create a listing on Vrbo",
41983
+ "description": "Creates the listing on Vrbo in the host's connected Vrbo account, from the listing's content: title and description, property type, rooms and beds, amenities, photos, house rules (guests, minimum age, children, pets, smoking, events), check-in and check-out times, minimum stay, advance notice and booking window, the nightly price, cleaning, pet and extra-guest fees, the cancellation policy and the licence number. Vrbo's automatic new-listing discount is turned off so the listing sells at your prices.\n\n**It is a job.** Vrbo's onboarding takes 5\u201315 minutes (photos go up one at a time), so this answers `202` with `job.jobId`. Poll `GET /v1/listings/{id}/publish/vrbo?jobId=` for each finished step. When Vrbo has published the listing, that read links the new Vrbo unit to the listing with calendar sync on and queues the whole calendar (prices, availability, minimum stay) to Vrbo: **keep polling until `linked` is true.**\n\n**Which account.** A workspace with one Vrbo account needs nothing. With several, name it with `accountId` (`\"vrbo:13\"`, as the connection id). An account connected with messaging access is refused with `403 vrbo_messaging_access`.\n\n**Missing content** (street address, city, photos, nightly price, description) is refused with `422 listing_incomplete` naming what is missing. A listing already linked to a Vrbo unit is `409 listing_already_on_vrbo`. A run that failed part-way leaves an unpublished Vrbo property: publishing again completes it instead of creating a second one.\n\nThis creates a Vrbo listing. Prices, availability and minimum stay on an existing one change through `PUT /v1/availability/{propertyId}`; other content of an existing Vrbo listing is edited on Vrbo.",
41984
+ "tags": [
41985
+ "Listings"
41986
+ ],
41987
+ "parameters": [
41988
+ {
41989
+ "name": "id",
41990
+ "in": "path",
41991
+ "required": true,
41992
+ "description": "Repull listing id",
41993
+ "schema": {
41994
+ "type": "integer"
41995
+ }
41996
+ }
41997
+ ],
41998
+ "requestBody": {
41999
+ "required": false,
42000
+ "content": {
42001
+ "application/json": {
42002
+ "schema": {
42003
+ "type": "object",
42004
+ "properties": {
42005
+ "accountId": {
42006
+ "type": "string",
42007
+ "description": "The Vrbo account, as its connection id (`\"vrbo:13\"`) or the bare number. Needed only when the workspace has several."
42008
+ },
42009
+ "propertyId": {
42010
+ "type": "string",
42011
+ "description": "Finish this unpublished Vrbo property (from a failed run's `job.propertyId`) instead of starting a new one."
42012
+ }
42013
+ },
42014
+ "additionalProperties": false
42015
+ }
42016
+ }
42017
+ }
42018
+ },
42019
+ "responses": {
42020
+ "202": {
42021
+ "description": "Creation started",
42022
+ "content": {
42023
+ "application/json": {
42024
+ "schema": {
42025
+ "type": "object",
42026
+ "properties": {
42027
+ "listingId": {
42028
+ "type": "integer"
42029
+ },
42030
+ "channel": {
42031
+ "type": "string",
42032
+ "enum": [
42033
+ "vrbo"
42034
+ ]
42035
+ },
42036
+ "job": {
42037
+ "type": "object",
42038
+ "properties": {
42039
+ "jobId": {
42040
+ "type": "string",
42041
+ "description": "Pass to `GET /v1/listings/{id}/publish/vrbo?jobId=`."
42042
+ },
42043
+ "status": {
42044
+ "type": "string",
42045
+ "enum": [
42046
+ "running",
42047
+ "done",
42048
+ "failed"
42049
+ ]
42050
+ },
42051
+ "listingId": {
42052
+ "type": "integer"
42053
+ },
42054
+ "accountId": {
42055
+ "type": "integer",
42056
+ "description": "The Vrbo account (connection `vrbo:<accountId>`) the listing is created in."
42057
+ },
42058
+ "steps": {
42059
+ "type": "array",
42060
+ "items": {
42061
+ "type": "string"
42062
+ },
42063
+ "description": "Steps Vrbo has finished, in order: create, amenities, property type, rooms, photos, headline + description, house rules, rate, booking options, publish, fees, cancellation policy, \u2026"
42064
+ },
42065
+ "error": {
42066
+ "type": "string",
42067
+ "nullable": true,
42068
+ "description": "Vrbo's reason when `status` is `failed`."
42069
+ },
42070
+ "vrboListingNumber": {
42071
+ "type": "string",
42072
+ "nullable": true,
42073
+ "description": "The new Vrbo listing number, once Vrbo has published it."
42074
+ },
42075
+ "propertyId": {
42076
+ "type": "string",
42077
+ "nullable": true,
42078
+ "description": "The Vrbo property being built. Send it back as `propertyId` to finish a run that failed part-way."
42079
+ },
42080
+ "linked": {
42081
+ "type": "boolean",
42082
+ "description": "The new Vrbo unit is linked to the listing with calendar sync on, and the whole calendar has been queued to Vrbo."
42083
+ },
42084
+ "rejectedPhotos": {
42085
+ "type": "array",
42086
+ "items": {
42087
+ "type": "object",
42088
+ "properties": {
42089
+ "photo": {
42090
+ "type": "integer",
42091
+ "nullable": true
42092
+ },
42093
+ "reason": {
42094
+ "type": "string"
42095
+ }
42096
+ }
42097
+ },
42098
+ "description": "Photos Vrbo's review refused (position in the listing's order, and Vrbo's reason)."
42099
+ },
42100
+ "adjustments": {
42101
+ "type": "array",
42102
+ "items": {
42103
+ "type": "string"
42104
+ },
42105
+ "description": "POST only: where the Vrbo listing departs from the listing's content because of a Vrbo rule."
42106
+ },
42107
+ "resumedPropertyId": {
42108
+ "type": "string",
42109
+ "nullable": true,
42110
+ "description": "POST only: set when an unfinished Vrbo property of this listing is completed instead of starting a new one."
42111
+ }
42112
+ }
42113
+ }
42114
+ }
42115
+ }
42116
+ }
42117
+ }
42118
+ },
42119
+ "400": {
42120
+ "$ref": "#/components/responses/BadRequest"
42121
+ },
42122
+ "403": {
42123
+ "description": "`listing_inactive`, or `vrbo_messaging_access`: the account is connected with messaging access.",
42124
+ "content": {
42125
+ "application/json": {
42126
+ "schema": {
42127
+ "$ref": "#/components/schemas/Error"
42128
+ }
42129
+ }
42130
+ }
42131
+ },
42132
+ "404": {
42133
+ "$ref": "#/components/responses/NotFound"
42134
+ },
42135
+ "409": {
42136
+ "description": "`listing_already_on_vrbo`, `vrbo_not_connected`, or `ambiguous_vrbo_account` (name it with `accountId`).",
42137
+ "content": {
42138
+ "application/json": {
42139
+ "schema": {
42140
+ "$ref": "#/components/schemas/Error"
42141
+ }
42142
+ }
42143
+ }
42144
+ },
42145
+ "422": {
42146
+ "description": "`listing_incomplete`: the listing lacks something Vrbo requires; `message` names it.",
42147
+ "content": {
42148
+ "application/json": {
42149
+ "schema": {
42150
+ "$ref": "#/components/schemas/Error"
42151
+ }
42152
+ }
42153
+ }
42154
+ },
42155
+ "502": {
42156
+ "description": "`vrbo_error`: Vrbo did not complete the request.",
42157
+ "content": {
42158
+ "application/json": {
42159
+ "schema": {
42160
+ "$ref": "#/components/schemas/Error"
42161
+ }
42162
+ }
42163
+ }
42164
+ }
42165
+ }
42166
+ },
42167
+ "get": {
42168
+ "operationId": "getVrboPublishJob",
42169
+ "summary": "Progress of a Vrbo listing creation",
42170
+ "description": "Each step Vrbo has finished, Vrbo's reason when it failed, the new Vrbo listing number once published, and photos Vrbo's review refused. When Vrbo has published the listing, this read links the new unit to the listing with calendar sync on and queues the whole calendar \u2014 poll until `linked` is true. A job is remembered while it runs and for a while after; an unknown job is `404` (publish again to resume).",
42171
+ "tags": [
42172
+ "Listings"
42173
+ ],
42174
+ "parameters": [
42175
+ {
42176
+ "name": "id",
42177
+ "in": "path",
42178
+ "required": true,
42179
+ "description": "Repull listing id",
42180
+ "schema": {
42181
+ "type": "integer"
42182
+ }
42183
+ },
42184
+ {
42185
+ "name": "jobId",
42186
+ "in": "query",
42187
+ "required": true,
42188
+ "description": "`job.jobId` from the POST.",
42189
+ "schema": {
42190
+ "type": "string"
42191
+ }
42192
+ }
42193
+ ],
42194
+ "responses": {
42195
+ "200": {
42196
+ "description": "Job state",
42197
+ "content": {
42198
+ "application/json": {
42199
+ "schema": {
42200
+ "type": "object",
42201
+ "properties": {
42202
+ "listingId": {
42203
+ "type": "integer"
42204
+ },
42205
+ "channel": {
42206
+ "type": "string",
42207
+ "enum": [
42208
+ "vrbo"
42209
+ ]
42210
+ },
42211
+ "job": {
42212
+ "type": "object",
42213
+ "properties": {
42214
+ "jobId": {
42215
+ "type": "string",
42216
+ "description": "Pass to `GET /v1/listings/{id}/publish/vrbo?jobId=`."
42217
+ },
42218
+ "status": {
42219
+ "type": "string",
42220
+ "enum": [
42221
+ "running",
42222
+ "done",
42223
+ "failed"
42224
+ ]
42225
+ },
42226
+ "listingId": {
42227
+ "type": "integer"
42228
+ },
42229
+ "accountId": {
42230
+ "type": "integer",
42231
+ "description": "The Vrbo account (connection `vrbo:<accountId>`) the listing is created in."
42232
+ },
42233
+ "steps": {
42234
+ "type": "array",
42235
+ "items": {
42236
+ "type": "string"
42237
+ },
42238
+ "description": "Steps Vrbo has finished, in order: create, amenities, property type, rooms, photos, headline + description, house rules, rate, booking options, publish, fees, cancellation policy, \u2026"
42239
+ },
42240
+ "error": {
42241
+ "type": "string",
42242
+ "nullable": true,
42243
+ "description": "Vrbo's reason when `status` is `failed`."
42244
+ },
42245
+ "vrboListingNumber": {
42246
+ "type": "string",
42247
+ "nullable": true,
42248
+ "description": "The new Vrbo listing number, once Vrbo has published it."
42249
+ },
42250
+ "propertyId": {
42251
+ "type": "string",
42252
+ "nullable": true,
42253
+ "description": "The Vrbo property being built. Send it back as `propertyId` to finish a run that failed part-way."
42254
+ },
42255
+ "linked": {
42256
+ "type": "boolean",
42257
+ "description": "The new Vrbo unit is linked to the listing with calendar sync on, and the whole calendar has been queued to Vrbo."
42258
+ },
42259
+ "rejectedPhotos": {
42260
+ "type": "array",
42261
+ "items": {
42262
+ "type": "object",
42263
+ "properties": {
42264
+ "photo": {
42265
+ "type": "integer",
42266
+ "nullable": true
42267
+ },
42268
+ "reason": {
42269
+ "type": "string"
42270
+ }
42271
+ }
42272
+ },
42273
+ "description": "Photos Vrbo's review refused (position in the listing's order, and Vrbo's reason)."
42274
+ },
42275
+ "adjustments": {
42276
+ "type": "array",
42277
+ "items": {
42278
+ "type": "string"
42279
+ },
42280
+ "description": "POST only: where the Vrbo listing departs from the listing's content because of a Vrbo rule."
42281
+ },
42282
+ "resumedPropertyId": {
42283
+ "type": "string",
42284
+ "nullable": true,
42285
+ "description": "POST only: set when an unfinished Vrbo property of this listing is completed instead of starting a new one."
42286
+ }
42287
+ }
42288
+ }
42289
+ }
42290
+ }
42291
+ }
42292
+ }
42293
+ },
42294
+ "400": {
42295
+ "$ref": "#/components/responses/BadRequest"
42296
+ },
42297
+ "404": {
42298
+ "$ref": "#/components/responses/NotFound"
42299
+ },
42300
+ "502": {
42301
+ "description": "`vrbo_error`",
42302
+ "content": {
42303
+ "application/json": {
42304
+ "schema": {
42305
+ "$ref": "#/components/schemas/Error"
42306
+ }
42307
+ }
42308
+ }
42309
+ }
42310
+ }
42311
+ }
42312
+ },
42313
+ "/v1/reservations/summary": {
42314
+ "get": {
42315
+ "operationId": "get_reservation_summary",
42316
+ "summary": "Summarize reservations for a period",
42317
+ "description": "Bookings, nights, revenue, payout, average nightly rate, occupancy and cancellations for a period, in one small response \u2014 optionally grouped by `month`, `listing` and/or `channel`. Use it for reporting instead of paging through `GET /v1/reservations`.\n\n**Counting (`basis`):** `stay` (default) counts the nights that fall inside `from`\u2013`to` and splits each reservation\u2019s money across its nights, so a stay crossing the window or a month edge brings only its share. `check_in` and `booked` count whole reservations by their check-in or booking date.\n\n**Pace (`as_of`):** keeps only what was on the books at the end of that day \u2014 booked by then and not yet cancelled. To compare the next three months with the same months last year like for like, ask for last year\u2019s window with `as_of` set to today\u2019s date one year ago.\n\nOwner stays are reported apart and never count as revenue or occupancy. Pending requests are counted in `pending` only. Reservations on inactive listings are left out.",
42318
+ "tags": [
42319
+ "Reservations"
42320
+ ],
42321
+ "parameters": [
42322
+ {
42323
+ "$ref": "#/components/parameters/Account"
42324
+ },
42325
+ {
42326
+ "name": "from",
42327
+ "in": "query",
42328
+ "required": true,
42329
+ "schema": {
42330
+ "type": "string",
42331
+ "format": "date",
42332
+ "example": "2026-11-10"
42333
+ },
42334
+ "description": "First day of the period."
42335
+ },
42336
+ {
42337
+ "name": "to",
42338
+ "in": "query",
42339
+ "required": true,
42340
+ "schema": {
42341
+ "type": "string",
42342
+ "format": "date",
42343
+ "example": "2027-02-09"
42344
+ },
42345
+ "description": "Last day of the period (inclusive). At most 732 days after `from`."
42346
+ },
42347
+ {
42348
+ "name": "basis",
42349
+ "in": "query",
42350
+ "required": false,
42351
+ "schema": {
42352
+ "type": "string",
42353
+ "enum": [
42354
+ "stay",
42355
+ "check_in",
42356
+ "booked"
42357
+ ],
42358
+ "default": "stay"
42359
+ },
42360
+ "description": "Which date puts a reservation in the period: the nights stayed (`stay`), the check-in date, or the booking date."
42361
+ },
42362
+ {
42363
+ "name": "group_by",
42364
+ "in": "query",
42365
+ "required": false,
42366
+ "schema": {
42367
+ "type": "string",
42368
+ "example": "month,listing"
42369
+ },
42370
+ "description": "Up to two of `month`, `listing`, `channel`, comma-separated. Omit for totals only."
42371
+ },
42372
+ {
42373
+ "name": "as_of",
42374
+ "in": "query",
42375
+ "required": false,
42376
+ "schema": {
42377
+ "type": "string",
42378
+ "format": "date",
42379
+ "example": "2025-11-10"
42380
+ },
42381
+ "description": "Count only what was on the books at the end of this day. A reservation cancelled without a reported cancellation date counts as cancelled."
42382
+ },
42383
+ {
42384
+ "name": "listing_id",
42385
+ "in": "query",
42386
+ "required": false,
42387
+ "schema": {
42388
+ "type": "integer"
42389
+ },
42390
+ "description": "One listing only."
42391
+ },
42392
+ {
42393
+ "name": "platform",
42394
+ "in": "query",
42395
+ "required": false,
42396
+ "schema": {
42397
+ "type": "string",
42398
+ "example": "airbnb"
42399
+ },
42400
+ "description": "One channel only."
42401
+ }
42402
+ ],
42403
+ "responses": {
42404
+ "200": {
42405
+ "description": "Totals for the period (one row per currency) and, when `group_by` is set, one row per group.",
42406
+ "content": {
42407
+ "application/json": {
42408
+ "schema": {
42409
+ "type": "object",
42410
+ "required": [
42411
+ "from",
42412
+ "to",
42413
+ "basis",
42414
+ "groupBy",
42415
+ "asOf",
42416
+ "totals",
42417
+ "groups",
42418
+ "listingCount"
42419
+ ],
42420
+ "properties": {
42421
+ "from": {
42422
+ "type": "string",
42423
+ "format": "date",
42424
+ "example": "2026-11-10"
42425
+ },
42426
+ "to": {
42427
+ "type": "string",
42428
+ "format": "date",
42429
+ "example": "2027-02-09"
42430
+ },
42431
+ "basis": {
42432
+ "type": "string",
42433
+ "enum": [
42434
+ "stay",
42435
+ "check_in",
42436
+ "booked"
42437
+ ]
42438
+ },
42439
+ "groupBy": {
42440
+ "type": "array",
42441
+ "items": {
42442
+ "type": "string",
42443
+ "enum": [
42444
+ "month",
42445
+ "listing",
42446
+ "channel"
42447
+ ]
42448
+ }
42449
+ },
42450
+ "asOf": {
42451
+ "type": "string",
42452
+ "format": "date",
42453
+ "nullable": true
42454
+ },
42455
+ "listingCount": {
42456
+ "type": "integer",
42457
+ "example": 19,
42458
+ "description": "Active listings covered (the occupancy denominator)."
42459
+ },
42460
+ "totals": {
42461
+ "type": "array",
42462
+ "items": {
42463
+ "type": "object",
42464
+ "required": [
42465
+ "currency",
42466
+ "reservations",
42467
+ "nights",
42468
+ "revenue",
42469
+ "payout",
42470
+ "cancelled",
42471
+ "pending",
42472
+ "ownerStays",
42473
+ "ownerNights"
42474
+ ],
42475
+ "properties": {
42476
+ "month": {
42477
+ "type": "string",
42478
+ "example": "2026-12",
42479
+ "description": "Present when grouped by `month` (YYYY-MM)."
42480
+ },
42481
+ "listingId": {
42482
+ "type": "string",
42483
+ "example": "4011",
42484
+ "description": "Present when grouped by `listing`."
42485
+ },
42486
+ "listingName": {
42487
+ "type": "string",
42488
+ "nullable": true,
42489
+ "example": "Lakeside Cabin",
42490
+ "description": "Present when grouped by `listing`."
42491
+ },
42492
+ "channel": {
42493
+ "type": "string",
42494
+ "example": "airbnb",
42495
+ "description": "Present when grouped by `channel`."
42496
+ },
42497
+ "currency": {
42498
+ "type": "string",
42499
+ "nullable": true,
42500
+ "example": "CAD",
42501
+ "description": "Money is never added across currencies: a period with two currencies has one row per currency."
42502
+ },
42503
+ "reservations": {
42504
+ "type": "integer",
42505
+ "example": 212,
42506
+ "description": "Guest stays with at least one night counted (owner stays are in `ownerStays`)."
42507
+ },
42508
+ "nights": {
42509
+ "type": "integer",
42510
+ "example": 1104,
42511
+ "description": "Guest nights counted."
42512
+ },
42513
+ "revenue": {
42514
+ "type": "number",
42515
+ "example": 18250.4,
42516
+ "description": "What guests paid (`financials.totalPrice`). With `basis=stay`, a stay that crosses the window or a month edge brings only the share of its nights inside."
42517
+ },
42518
+ "payout": {
42519
+ "type": "number",
42520
+ "example": 18250.4,
42521
+ "description": "What the host receives (`financials.host.revenue`), for reservations where it is known."
42522
+ },
42523
+ "reservationsWithPayout": {
42524
+ "type": "integer",
42525
+ "description": "How many reservations `payout` covers."
42526
+ },
42527
+ "averageNightlyRate": {
42528
+ "type": "number",
42529
+ "nullable": true,
42530
+ "example": 178.5,
42531
+ "description": "Accommodation per night (revenue per night when the accommodation subtotal is unknown)."
42532
+ },
42533
+ "averageStayNights": {
42534
+ "type": "number",
42535
+ "nullable": true,
42536
+ "example": 5.2
42537
+ },
42538
+ "averageLeadTimeDays": {
42539
+ "type": "number",
42540
+ "nullable": true,
42541
+ "example": 41,
42542
+ "description": "Days between booking and check-in."
42543
+ },
42544
+ "occupancy": {
42545
+ "type": "number",
42546
+ "nullable": true,
42547
+ "example": 0.6431,
42548
+ "description": "Guest nights / available nights, 0\u20131. Only with `basis=stay`, and not when grouped by `channel`. Blocked nights are not subtracted from availability."
42549
+ },
42550
+ "availableNights": {
42551
+ "type": "number",
42552
+ "nullable": true,
42553
+ "example": 1716,
42554
+ "description": "Active listings \u00d7 days in the period (one listing per row when grouped by `listing`)."
42555
+ },
42556
+ "cancelled": {
42557
+ "type": "integer",
42558
+ "example": 18
42559
+ },
42560
+ "cancelledRevenue": {
42561
+ "type": "number",
42562
+ "example": 18250.4
42563
+ },
42564
+ "pending": {
42565
+ "type": "integer",
42566
+ "example": 2,
42567
+ "description": "Requests awaiting an answer; not in revenue or nights."
42568
+ },
42569
+ "ownerStays": {
42570
+ "type": "integer",
42571
+ "example": 3
42572
+ },
42573
+ "ownerNights": {
42574
+ "type": "integer",
42575
+ "example": 12
42576
+ }
42577
+ }
42578
+ }
42579
+ },
42580
+ "groups": {
42581
+ "type": "array",
42582
+ "items": {
42583
+ "type": "object",
42584
+ "required": [
42585
+ "currency",
42586
+ "reservations",
42587
+ "nights",
42588
+ "revenue",
42589
+ "payout",
42590
+ "cancelled",
42591
+ "pending",
42592
+ "ownerStays",
42593
+ "ownerNights"
42594
+ ],
42595
+ "properties": {
42596
+ "month": {
42597
+ "type": "string",
42598
+ "example": "2026-12",
42599
+ "description": "Present when grouped by `month` (YYYY-MM)."
42600
+ },
42601
+ "listingId": {
42602
+ "type": "string",
42603
+ "example": "4011",
42604
+ "description": "Present when grouped by `listing`."
42605
+ },
42606
+ "listingName": {
42607
+ "type": "string",
42608
+ "nullable": true,
42609
+ "example": "Lakeside Cabin",
42610
+ "description": "Present when grouped by `listing`."
42611
+ },
42612
+ "channel": {
42613
+ "type": "string",
42614
+ "example": "airbnb",
42615
+ "description": "Present when grouped by `channel`."
42616
+ },
42617
+ "currency": {
42618
+ "type": "string",
42619
+ "nullable": true,
42620
+ "example": "CAD",
42621
+ "description": "Money is never added across currencies: a period with two currencies has one row per currency."
42622
+ },
42623
+ "reservations": {
42624
+ "type": "integer",
42625
+ "example": 212,
42626
+ "description": "Guest stays with at least one night counted (owner stays are in `ownerStays`)."
42627
+ },
42628
+ "nights": {
42629
+ "type": "integer",
42630
+ "example": 1104,
42631
+ "description": "Guest nights counted."
42632
+ },
42633
+ "revenue": {
42634
+ "type": "number",
42635
+ "example": 18250.4,
42636
+ "description": "What guests paid (`financials.totalPrice`). With `basis=stay`, a stay that crosses the window or a month edge brings only the share of its nights inside."
42637
+ },
42638
+ "payout": {
42639
+ "type": "number",
42640
+ "example": 18250.4,
42641
+ "description": "What the host receives (`financials.host.revenue`), for reservations where it is known."
42642
+ },
42643
+ "reservationsWithPayout": {
42644
+ "type": "integer",
42645
+ "description": "How many reservations `payout` covers."
42646
+ },
42647
+ "averageNightlyRate": {
42648
+ "type": "number",
42649
+ "nullable": true,
42650
+ "example": 178.5,
42651
+ "description": "Accommodation per night (revenue per night when the accommodation subtotal is unknown)."
42652
+ },
42653
+ "averageStayNights": {
42654
+ "type": "number",
42655
+ "nullable": true,
42656
+ "example": 5.2
42657
+ },
42658
+ "averageLeadTimeDays": {
42659
+ "type": "number",
42660
+ "nullable": true,
42661
+ "example": 41,
42662
+ "description": "Days between booking and check-in."
42663
+ },
42664
+ "occupancy": {
42665
+ "type": "number",
42666
+ "nullable": true,
42667
+ "example": 0.6431,
42668
+ "description": "Guest nights / available nights, 0\u20131. Only with `basis=stay`, and not when grouped by `channel`. Blocked nights are not subtracted from availability."
42669
+ },
42670
+ "availableNights": {
42671
+ "type": "number",
42672
+ "nullable": true,
42673
+ "example": 1716,
42674
+ "description": "Active listings \u00d7 days in the period (one listing per row when grouped by `listing`)."
42675
+ },
42676
+ "cancelled": {
42677
+ "type": "integer",
42678
+ "example": 18
42679
+ },
42680
+ "cancelledRevenue": {
42681
+ "type": "number",
42682
+ "example": 18250.4
42683
+ },
42684
+ "pending": {
42685
+ "type": "integer",
42686
+ "example": 2,
42687
+ "description": "Requests awaiting an answer; not in revenue or nights."
42688
+ },
42689
+ "ownerStays": {
42690
+ "type": "integer",
42691
+ "example": 3
42692
+ },
42693
+ "ownerNights": {
42694
+ "type": "integer",
42695
+ "example": 12
42696
+ }
42697
+ }
42698
+ }
42699
+ }
42700
+ }
42701
+ }
42702
+ }
42703
+ }
42704
+ },
42705
+ "401": {
42706
+ "$ref": "#/components/responses/Unauthorized"
42707
+ },
42708
+ "403": {
42709
+ "$ref": "#/components/responses/ListingInactive"
42710
+ },
42711
+ "422": {
42712
+ "$ref": "#/components/responses/UnprocessableEntity"
42713
+ },
42714
+ "500": {
42715
+ "$ref": "#/components/responses/InternalError"
42716
+ }
42717
+ }
42718
+ }
41678
42719
  }
41679
42720
  }
41680
42721
  }