[Deprecated] PCN API

Product Change Notifications (PCN) are http calls performed by Tiqets to your server, to notify you about products going off-sale, becoming available again or when their content is changed.

This page describes the Deprecated PCN system. It remains maintained for now but is scheduled removal. For all new implementations, please use the new PCN, documented here: [New] Product Change Notifications API

Introduction

By explicitly subscribing to PCN for specific products you ensure notifications are relevant for your business.

Notification include helpful context, such as the type of change and type-specific information such as estimated reopening time frames, and a suggested fallback product you can promote. This allows you to keep your catalog accurate, avoid promoting unavailable options, and continue offering relevant alternatives.

When is a Product Status Notification Sent?

When a product’s content or sale status changes then separate notifications are sent. This typically means:

• The product's description has changed

• A product that was available for booking becomes unavailable

• A previously unavailable product becomes available again

Per individually changed product a single notification is sent at a time.

The type of event is described by the change_type field in the notification request's body.

Currently supported types are:

• checkout - Changes to the product's sale_status, meaning that a product has gone on- or off-sale. If the checkout changes, the notification includes these additional fields:

  • reason (string enum: temporary_closure, out_of_season, other),

  • reopening_date (string enum: within_7_days, within_2_weeks, within_month, more_than_month),

  • alternative_product_id (integer).

• closure - Changes to the venue’s "closure dates". Venues and experience may occasionally temporarily close their business due to special circumstances.

• content- Changes in product information fields.

Example

Here's an example of a checkout type change notification.

{
  "product_id": 313373,
  "change_types": ["checkout"],
  "reason": "temporary_closure",
  "reopening_date": "within_7_days",
  "alternative_product_id": 555789
}

When a product becomes available again, another Product Status Notification is sent, but then the reason , reopening_date and and alternative_product_id fields will be set to null.

Subscribing to Product Change Notifications

To start receiving product status updates, you need to create a subscription. Subscriptions define which products you want to monitor and where Tiqets should send the notifications.

How it works

You can manage your subscriptions using the Tiqets Distributor API. Each subscription specifies:

• A target_endpoint: the URL where Tiqets will send notifications

• A list of product_ids: the specific products you want to monitor

You can create one or multiple subscription lists. For example, you might want separate subscriptions for your different markets, or to separate high-priority and low-priority products.

You will receive all types of change notifications for all products you are subscribed to. To track sale status changes, look for notifications with the checkout change type.

Notification delays

Notifications are not sent instantly. The change notifications for multiple products will be held for several minutes to avoid spamming you when multiple mutations are being done to the same product. Only the last mutation of the same type will be sent to you.

Creating a subscription

POST /v2/subscriptions/

{
  "name": "Important product list one",
  "subscription_type": "webhook",
  "target_endpoint": "https://partner/notification/url",
  "products": [
    {
      "product_id": 973888
    },
    {
      "product_id": 973666
    },
    {
      "product_id": 929249
    }
  ]
}

After creating the subscription, you will start receiving notifications for the selected products. Among these notifications, the ones with the checkout change type specifically indicate a change in the product’s sale status.

For more details on this and other PCN related operations, please refer to the API Reference

If you encounter any issues processing notifications, such as missing updates or unexpected retries, feel free to contact our technical support team.

How to Handle the Notification

When a product status change is detected, Tiqets sends a POST request to the endpoint you specified while subscribing. This request contains a JSON payload like the one shown before.

Your system should be prepared to:

1. Acknowledge the notification Return an HTTP 200 response to confirm successful delivery. If your server does not respond with a 200 status code, Tiqets will retry the notification using exponential backoff: after 20, 40, 80, 160, and 320 seconds. Note: the response body is ignored; only the HTTP status code matters.

2. Update your catalog based on the notification The notification payload contains all the information needed to update the product’s sale status immediately. You should deactivate products that became unavailable, and when an alternative_product_id is provided, consider promoting the suggested fallback product to maintain your conversion flow and avoid losing sales.

3. Use the additional context to plan ahead You can also make use of the following fields to improve your catalog management:

   • reason: Optionally display or log why the product is unavailable (e.g., seasonal closure, maintenance).

   • reopening_date: Plan when to relist the product based on its expected return timeframe.

Webhook Security

Managing subscriptions requires you to sign your requests, but no authentication mechanism applies to the HTTP calls Tiqets performs to you. For webhooks to work you need to open up one or multiple endpoints that are publically accessible.

To ensure those endpoint(s) don't get abused, here are two suggestions for increased security:

1. Whitelist our outgoing IP addresses;

2. Use very hard-to-guess URLs when subscribing to notifications;

1. Whitelisting IP addresses

The following IP addresses can be whitelisted:

99.80.191.99 (out.acceptance.steq.it) 63.35.71.28 (out.acceptance.steq.it) 63.35.56.49 (out.acceptance.steq.it)	99.81.16.132 (out.tiqets.com) 54.77.55.83 (out.tiqets.com) 34.246.210.158 (out.tiqets.com)

2. Hard-to-guess URLs

Another suggestion is to use hard to guess URLs, such as https://mydomain.com/webhooks/tiqets/ieAsjDlcm67hJacH643Ahc/

If you'd want to you could even update that URL periodically.