What's New in Product Catalog
Scope
Glossary of Terms
Product Catalog Overview
Using the Product Catalog Developer Portal
API Authentication
API Limitations
Success and Error Codes
Product Catalog Versions
Support
Subscription API

Notification and Subscription API

Notifications are used to inform subscribers when new or updated data is available for retrieval. Subscribers receive notifications only when relevant data packages are ready for them. These notifications act as a lightweight, event-driven signal to notify only the intended subscribers. Instead of continuously polling for updates, subscribers are alerted in real time, enabling efficient and secure data retrieval.

The Subscription API is the mechanism through which subscribers request and receive the new or updated Product Catalog data. Upon receipt of a notification, subscribers can call the API to retrieve the corresponding data package. This section outlines how Product Catalog distribution files are created, managed, and accessed through the Subscription API (pull model) as well as the push model.

Data Scope Enforcement

  • Sending notifications across organizations requires prior setup and agreed permissions on both sides.
  • Notifications can only be received once the target account has been configured to accept them.
  • Subscribers receive only the data they are authorized to access, as defined by the Catalog Owner’s policy and data scope. For authorization controls and policies refer to Product Catalog Onboarding Guide.

Change Management Activities

ATPCO executes change management activities to ensure that Product Catalog data is:

  • Synchronized with data that is auto populated from ATPCO source systems: Optional Services (S5), Amenities, Branded Fares (S8), Fares (for Transport OD products) and Fare Data Linked data (Fare Rule Merged data resolved to a Brand bundle)
  • Aligned with updates made via the Intake APIs

Change management ensures that data is consistent and accurate for all consuming systems.

Notification

Notifications are used to inform subscribers when new or updated data is available for retrieval. Subscribers receive notifications only when relevant data packages are ready for them. These notifications act as a lightweight, event-driven signal to notify only the intended subscribers. Instead of continuously polling for updates, subscribers are alerted in real time, enabling efficient and secure data retrieval.

Subscriber Responsibilities

Upon receiving a notification, the subscriber should be able to parse the notification and extract the needed message Id and call the subscription API to retrieve the package. Subscriber should also handle duplicate notifications gracefully since the notification service is “at-least once delivery”

📝 The notification is a signal, not the data itself. The API is the source of truth.

Types of Delivery Methods for Subscription

ATPCO offers two delivery methods for their product catalog subscription:

  • S3 Push — A notification is sent first, followed by the generated file being pushed to a secured S3 location. The notification can be used as a trigger to process the file.
  • API Request for Pull — The subscriber first receives a notification which serves as a trigger. They then call the API to get the package location and pull the catalog from the received endpoint.

delivery-methods-pc-subscription.png

There are two types of Subscription data that can be delivered via S3-push or API-pull.

Subscription Data TypeDescription
Change DataCatalog data for the authorized subscriber that has changed since the last request (e.g., adds, updates, and deletes)
All-AddsAll catalog data that is authorized for the subscriber

S3-Push for Change Data

To deliver files via S3 Push, the following setup is agreed and exchanged between ATPCO and the subscriber upfront.

  • Access method — Both parties agree on how ATPCO will authenticate to the subscriber's storage, such as through cross-account IAM roles or access key credentials.
  • Permissions — The subscriber grants ATPCO the minimum access needed to deliver files, such as the ability to write or list objects within the designated storage folder.
  • Storage details — The subscriber provides the specific bucket name, AWS region, and any encryption requirements that ATPCO must comply with when pushing files.

Once this information is in place, ATPCO configures the delivery pipeline accordingly, and file pushing can begin.

API-Pull for Change Data

After receiving the notification subscribers initiate a GET request to the subscription API to receive change data.

The API returns data from the most recently completed change cycle.

Request for Change DataSubscription API Response
Subscriber provides the request type and the ID of the subscriber.
Example:
Method: GET
Path: /subscriptions? requestType=changes&subscriptionId=<subscriber ID>		Response provides download instructions.
Example:
{
“downloadInstruction” :
    “downloadUrls” : [ ],
    “availabilityTime” : “ ”,
    “message” : “ ”,
    “details” : “ ”
}

Change File Retention Policy

The change file retention policy is based on the delivery method.

Delivery MethodDistribution File Retention Period
S3-PushDepends on the subscribers S3 retention policy
API-PushAll change up to 7 days of the previous request

📝 If change files are not retrieved within the file retention period, the subscriber must request an All-Adds distribution.

No File Aggregation

Each change file is a standalone snapshot of each change notification — no aggregation is performed. When multiple change files are retrieved, subscribers must apply the data in the order in which the files were generated.

File Naming Convention

ZIP File Naming Structure for Change Files

<sub-org-id>.<env>.PCC.<DATE IN YYMMDD>.<TIME in HHMM>.zip

ExampleDescription
11.GOLD.PCC.D20260303.T1150.zip11 – Subscriber Org id
GOLD – Is the environment
PCC – Product Catalog change data
D260303 – Date in YYYYMMDD format
T1150 – Time is HHMM format

Individual Files Inside the Zip

<catalog-owner-org id>_<sub org id>_<Work Unit id>.json

ExamplesDescription
XX_11_ATP-31MAR26-26.json
  • XX – Catalog Owner
  • 11 - Subscriber Org id
  • ATP-31MAR26-26 – WorkUnit ID – which is the reference to changed content
ZZ_11_ATP-31MAR26-26.json
  • ZZ – Catalog Owner
  • 11 - Subscriber Org id
  • ATP-31MAR26-26 – WorkUnit ID – which is the reference to changed content

All-Adds Subscription

The All-Adds process provides subscribers with a full snapshot of their Product Catalog data as it existed at the end of the most recently completed change cycle. This process is essential for new subscribers, system resets, or recovery situations, and is initiated through a two-step API request sequence.

Initiating the All-Adds Process

The All-Adds process begins when a subscriber sends a GET request to the Subscription API, specifying their need for full data to load.

Step 1: Submit All-Adds Request

  • The subscriber sends a GET request containing:
    • Subscriber ID
    • All-Adds Request Type
  • The system responds with:
    • A unique All-Adds Request ID
    • The date and time when the All-Adds data file will be ready for download

The timing of the request determines when the file is generated and what data it contains. A request can be submitted at any time.

If the request is received before the top of an hour, the file is generated based on data up to the previous hour.

Each request produces more than one file, organized per Catalog Owner:

  • File 1 — Contains all data as is till the previous hour (the All-Adds file).
  • File 2 onwards — Covers every change that occurred at and after the top of the hour.

Once the All-Adds request is received, all corresponding change files are automatically generated and made available without any additional action required

Retrieving the All-Adds File

Step 2: Request File Download Information API-Pull/Receives File for S3-Push

  • S3-PUSH - ATPCO pushes the files directly into the agreed and secured storage location. Files are also retained on ATPCO's side to support recovery in the event of missed deliveries or corrupted files.
  • API- PULL - Once the All-Adds file is ready, the subscriber sends a second GET request, which includes:
    • Subscriber ID
    • The previously received All-Adds Request ID
    • The response includes Download instructions for accessing the All-Adds file from a secured location

Example for API-Pull

Step 2. Request for Data RetrievalSubscription API Response
The subscriber provides the request type, the ID of the subscriber, and the All-Adds request ID.
Example:
Method: GET
Path: /subscriptions? requestType=all&subscriptionId=<subscriber ID>& allAddsRequestId=<request Id>		The response provides download instructions.
Example:
{
“downloadInstruction” :
    “downloadUrls” : [ ],
    “availabilityTime” : “ ”,
    “message” : “ ”,
    “details” : “ ”
}

File Content, Timing and Security

  • The All-Adds file reflects the state of the Product Catalog at the end of the most recent change cycle.
  • API-PULL: The download URL comes with the secure token and ensures only the valid recipient can access the data. The token has a limited validity period and expires after a set time.
  • API-PUSH: ATPCO pushes the files directly into the agreed and secured storage location.

Important Notes for Subscribers

  • Submitting an All-Adds request does not replace change data requests.
  • Subscribers must resume requesting change data or receive change data for all subsequent change cycles after completing the All-Adds process.
  • ATPCO strongly recommends the following load sequence:
    • First, load the All-Adds file
    • Then, apply the next available change file to ensure data consistency