Promos

These events are emitted by the Inventory API (btrz-api-inventory) when promos are created, updated, or disabled.

Events

Action Event name Endpoint
Create a promo promo.created POST /promos
Update promo fields promo.updated PATCH /promos/:promoId
Update rule availability only promo.updated PATCH /promo/:promoId
Replace a promo rule promo.updated PUT /promos/:promoId/rules/:ruleId
Disable a promo promo.deleted DELETE /promos/:promoId
Add a new promo rule promo.updated POST /promos/:promoId/rules

Payload example (envelope shape; data is the Promo resource)

{
  "id": "string",
  "attemptId": "string",
  "livemode": true,
  "created": 1623859265,
  "event": "promo.created",
  "data": {
    "_id": "string",
    "accountId": "string",
    "internalId": "string",
    "name": "string",
    "campaign": "string",
    "disabled": false,
    "deleted": false,
    "autoApply": false,
    "paymentMethodTypes": [],
    "appliesOnlyWhenLoggedIn": false,
    "cancellable": true,
    "changeable": true,
    "rules": [],
    "validPeriod": {
      "from": { "value": "string", "offset": 0 },
      "to": { "value": "string", "offset": 0 }
    },
    "createdBy": "string",
    "updatedBy": "string",
    "createdByUserEmail": "string",
    "updatedByUserEmail": "string",
    "createdAt": { "value": "string", "offset": 0 },
    "updatedAt": { "value": "string", "offset": 0 }
  }
}

event is promo.created, promo.updated, or promo.deleted. The data object is the persisted promo document at the time of the event. It matches the Inventory API Promo / PromoRule definitions, plus any extra keys present in Mongo (legacy fields, older documents, etc.).

Field descriptions — envelope

Field Type Description
id string Unique id of the webhook event.
attemptId string Id of the delivery attempt.
livemode boolean Whether the event is from live or test mode.
created number Unix timestamp when the event was created.
event string promo.created, promo.updated, or promo.deleted.
data object Promo document for that operation (see below).

Field descriptions — data (Promo)

Field Type Description
data._id string Promo id (MongoDB ObjectId string).
data.accountId string Account (provider) id.
data.internalId string Shown id of the promo (e.g. code).
data.name string Name of the promo.
data.campaign string Campaign the promo belongs to.
data.disabled boolean Whether the promo is disabled.
data.deleted boolean Whether the promo is marked deleted.
data.rules array Promo rules (PromoRule); see also the rule fields below.
data.validPeriod object Optional promo-level validity (ValidPeriod / BzDate fields).
data.autoApply boolean When true, the platform may auto-apply this promo when adding items to a cart.
data.paymentMethodTypes array of string Payment method ids allowed for this promo.
data.appliesOnlyWhenLoggedIn boolean
data.cancellable boolean When this promo is applied to a ticket, it will be cancellable unless another rule prevents it.
data.changeable boolean When this promo is applied to a ticket, it will be changeable unless another rule prevents it.
data.cancellableOverridesFare boolean This promo’s cancellable flag overrides the fare.
data.changeableOverridesFare boolean This promo’s changeable flag overrides the fare.
data.userId string User id associated with creation (per API model).
data.createdBy string User id that created the resource.
data.updatedBy string User id that last updated the resource.
data.createdByUserEmail string Email of the user that created the resource.
data.updatedByUserEmail string Email of the user that last updated the resource.
data.createdAt object BzDate: when the promo was created.
data.updatedAt object BzDate: when the promo was last updated.
data.valueType string
data.value integer
data.from string
data.to string
data.fare string
data.productType string
data.productId string
data.qty integer
data.available integer

For each property on data.rules[], refer to the Inventory API PromoRule schema. The following rule fields are defined in swagger for minimum-passenger / group-style behaviour (descriptions taken from the API model):

Field descriptions — selected data.rules[] (PromoRule) fields

Field Type Description
minPassengersQty integer Minimum passengers required for the rule to apply. When greater than zero, sales counts distinct passengers from cart reservation lines: rows sharing the same journeyId (one id per passenger-direction bundle from setJourney) and fare class / fare id collapse to one; roundtrip outbound and return (different journeyIds) merge when associatedRoundtripTicket links them. excludedFareTypes and requireSameOperation apply as documented on those fields.
requireSameOperation boolean When minPassengersQty is greater than zero and this flag is true, only reservation lines in the same cart checkout operation count toward the minimum. In sales this matches ticket lines that share the same operationId (one checkout operation can include multiple journeys).
excludedFareTypes array of string When minPassengersQty is greater than zero, fareId is empty, and this list is non-empty, passengers with these fare types do not count toward the minimum. Must be empty when fareId is set. Each id must belong to the rule productId.

Other PromoRule properties (e.g. value, valueType, validChannels, seatClassLimits, productId, fareId, travelDate, qty, available, …) are documented on the Inventory PromoRule definition in swagger.