> For the complete documentation index, see [llms.txt](https://developer.ivvy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.ivvy.com/notifications/venue-notifications/venue-notification-subscribe.md).

# Subscribe

## Subscribe To Venue Notifications

<mark style="color:green;">`POST`</mark> `[PlatformAddress]/api/1.0/venue?action=subscribeToNotifications`

Creates a notification subscription for a specific venue.

The API key must have access to the specified venue for the subscription to be created.

Notifications are delivered via AWS SNS and follow the same structure as the account-level Notifications API.

#### Request Body

| Name                                       | Type    | Description                                           |
| ------------------------------------------ | ------- | ----------------------------------------------------- |
| venueId<mark style="color:red;">\*</mark>  | integer | The unique identifier of the venue to subscribe to    |
| endpoint<mark style="color:red;">\*</mark> | string  | The HTTPS URL that will receive notification payloads |

{% tabs %}
{% tab title="200 " %}

```json
{
    "success": true,
    "topicId": "arn:aws:sns:ap-southeast-2:123456789012:venue-12345",
    "error": null
}
```

{% endtab %}
{% endtabs %}

This endpoint creates a notification subscription for the specified venue. Once created, AWS SNS will send a `SubscriptionConfirmation` request to your endpoint. You must confirm the subscription by visiting the `SubscribeURL` included in that request before notifications will be delivered.

**Note:** Only HTTPS endpoints are supported. HTTP endpoints will be rejected.

## Returns

| Property | Type    | Description                                                                             |
| -------- | ------- | --------------------------------------------------------------------------------------- |
| success  | boolean | Indicates whether the subscription was created successfully                             |
| topicId  | string  | The AWS SNS topic ARN associated with this subscription. Returns `null` if unsuccessful |
| error    | string  | A description of why the subscription failed. Returns `null` on success                 |

## Example Notification Payload

```json
{
    "Type": "Notification",
    "MessageId": "95df01b4-ee98-5cb9-9903-4c221d41eb5e",
    "TopicArn": "arn:aws:sns:ap-southeast-2:123456789012:venue-12345",
    "Subject": "booking.updated",
    "Message": "{\"TxnId\":\"ABC123\",\"SourceType\":\"venue\",\"VenueId\":12345}",
    "Timestamp": "2026-05-20T01:20:15.000Z",
    "SignatureVersion": "1",
    "Signature": "EXAMPLEw6JRN...",
    "SigningCertURL": "https://sns.ap-southeast-2.amazonaws.com/SimpleNotificationService.pem",
    "UnsubscribeURL": "https://sns.ap-southeast-2.amazonaws.com/?Action=Unsubscribe..."
}
```

## Error Response Example

When a subscription cannot be created, the response will include an error message:

```json
{
    "success": false,
    "topicId": null,
    "error": "The endpoint is already associated with another subscription."
}
```

### Common Errors

| Error                                                        | Description                                            |
| ------------------------------------------------------------ | ------------------------------------------------------ |
| The endpoint is already associated with another subscription | The URL is already subscribed to this or another venue |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.ivvy.com/notifications/venue-notifications/venue-notification-subscribe.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.