Yelp Business Subscriptions API
Business Subscriptions operations documented in the Yelp developer reference: Get Business Subscriptions; Subscribe to businesses; Unsubscribe from businesses; Get Quota.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/yelp:yelp-business-subscriptions-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Business Subscriptions API
version: '1.0'
servers:
- url: https://api.yelp.com/v3/businesses/
security:
- bearerAuth: []
tags:
- name: Business Subscriptions
paths:
/subscriptions:
get:
tags:
- Business Subscriptions
summary: Get Business Subscriptions
description: 'Retrieve a paginated list of business subscriptions for a given subscription type.
Example:
To fetch the first 100 business subscriptions of type WEBHOOK, sent a GET request to the following URL:
https://api.yelp.com/v3/businesses/subscriptions?subscription_type=WEBHOOK
For the above request a successful GET call will return at most 100 business subscriptions with the following response body:
```json
{
"total": 2,
"offset": 0,
"limit": 100,
"subscription_type": "WEBHOOK",
"subscriptions": [
{"business_id": "4U9kSBLuBDU391x6bxU-YA", "subscribed_at": "2022-12-10T09:50:00+00"},
{"business_id": "7w8SVwIEhxZ7jPnMUFYrng", "subscribed_at": "2022-12-10T10:52:30+00"},
]
}
```
**Note**: Each subscription type requires configuration by Yelp to access, please reach out to partner-support@yelp.com to configure access.'
operationId: get_business_subscriptions
parameters:
- name: subscription_type
required: true
in: query
schema:
description: Type of subscriptions being returned
type: string
enum:
- LISTING_MANAGEMENT
- YELP_KNOWLEDGE
- WEBHOOK
- name: limit
description: The maximum number of business subscriptions to return.
in: query
required: false
schema:
type: integer
default: 100
minimum: 0
maximum: 10000
- name: offset
description: Offset the list of returned business subscriptions by this amount.
in: query
required: false
schema:
type: integer
default: 0
minimum: 0
responses:
'200':
description: Successfully fetched the business subscriptions
content:
application/json:
examples:
Result:
value:
total: 2
offset: 0
limit: 100
subscription_type: WEBHOOK
subscriptions:
- business_id: 4U9kSBLuBDU391x6bxU-YA
subscribed_at: '2022-12-10T09:50:00+00'
- business_id: 7w8SVwIEhxZ7jPnMUFYrng
subscribed_at: '2022-12-10T10:52:30+00'
schema:
type: object
properties:
subscriptions:
description: List of active subscriptions
type: array
items:
type: object
properties:
business_id:
$ref: '#/paths/~1subscriptions/post/requestBody/content/application~1json/schema/properties/business_ids/items'
subscribed_at:
description: The time when the subscription got created
type: string
format: date-time
subscription_type:
$ref: '#/paths/~1subscriptions/get/parameters/0/schema'
total:
description: Total number of active subscriptions for the specified subscription type.
type: integer
offset:
description: Current offset
type: integer
limit:
description: Current limit
type: integer
required:
- subscriptions
- subscription_type
- total
- offset
- limit
'400':
description: Bad Request. Message varies depending on failure scenario
content:
application/json:
schema:
type: object
properties:
error:
type: object
required:
- code
- description
properties:
code:
type: string
description: The error code.
description:
type: string
description: The description of the error.
examples:
Invalid Request:
value:
error:
code: INVALID_REQUEST
description: Invalid Request
'401':
description: 'The API key has either expired or doesn''t have the required scopes to query this endpoint.
| code | description |
| ------------- | ------------- |
| UNAUTHORIZED_API_KEY | The API key provided is not currently able to query this endpoint. |
| TOKEN_INVALID | Invalid API key or authorization header. |
'
content:
application/json:
examples:
Unauthorized:
value:
error:
code: UNAUTHORIZED_API_KEY
description: The API key provided is not currently able to query this endpoint.
Invalid Token:
value:
error:
code: TOKEN_INVALID
description: Invalid API key or authorization header.
schema:
$ref: '#/paths/~1subscriptions/get/responses/400/content/application~1json/schema'
'403':
description: 'This error is returned in any of the following scenarios:
- The API key provided is not currently able to query this endpoint or manage business subscriptions of a certain type
- Trying to access a Partner API endpoint for which the API Client has not been enabled
| code | description |
| ----- | ------------------ |
| PARTNER_ENDPOINT_DISABLED | You are trying to access a Partner API endpoint for which your API Client has not been enabled. Please reach out to partner-support@yelp.com for more information. |
| AUTHORIZATION_ERROR | Authorization Error |
'
content:
application/json:
schema:
$ref: '#/paths/~1subscriptions/get/responses/400/content/application~1json/schema'
examples:
Partner Endpoint Disabled:
value:
error:
code: PARTNER_ENDPOINT_DISABLED
description: You are trying to access a Partner API endpoint for which your API Client has not been enabled. Please reach out to partner-support@yelp.com for more information.
Authorization Error:
value:
error:
code: AUTHORIZATION_ERROR
description: Authorization Error
'429':
description: You have either exceeded your daily quota, or have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries.
content:
application/json:
examples:
Rate limited:
value:
error:
code: TOO_MANY_REQUESTS_PER_SECOND
description: You have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries.
schema:
$ref: '#/paths/~1subscriptions/get/responses/400/content/application~1json/schema'
'500':
description: Internal Server Error
content:
application/json:
examples:
Internal Server Error:
value:
error:
code: INTERNAL_ERROR
description: Something went wrong internally, please try again later.
schema:
$ref: '#/paths/~1subscriptions/get/responses/400/content/application~1json/schema'
post:
tags:
- Business Subscriptions
summary: Subscribe to businesses
description: 'Create business subscriptions of the given types. Subscriptions are created asynchronously after a request is accepted.
There is a maximum number of subscriptions with type YELP_KNOWLEDGE that can be active in the current month. Use Get Quota to retrieve the quota information.
Example:
To create business subscriptions of type LISTING_MANAGEMENT and YELP_KNOWLEDGE for two businesses, sent a POST request to the following URL:
https://api.yelp.com/v3/businesses/subscriptions
Containing the following request body:
```json
{
"subscription_types": ["LISTING_MANAGEMENT", "YELP_KNOWLEDGE"],
"business_ids": ["4U9kSBLuBDU391x6bxU-YA", "7w8SVwIEhxZ7jPnMUFYrng"]
}
```
**Note**: Each subscription type requires configuration by Yelp to access, please reach out to partner-support@yelp.com to configure access.'
operationId: create_business_subscriptions
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
subscription_types:
type: array
description: Types of subscriptions that will be managed
items:
$ref: '#/paths/~1subscriptions/get/parameters/0/schema'
business_ids:
type: array
description: List of Yelp Encrypted Business IDs that will be managed.
items:
type: string
description: Yelp Encrypted Business ID.
minItems: 1
maxItems: 1000
uniqueItems: true
required:
- subscription_types
- business_ids
responses:
'202':
description: Request accepted. The business subscriptions will be created asynchronously
content:
application/json:
schema:
type: object
'400':
$ref: '#/paths/~1subscriptions/get/responses/400'
'401':
$ref: '#/paths/~1subscriptions/get/responses/401'
'403':
description: 'This error is returned in any of the following scenarios:
- The API key provided is not currently able to query this endpoint or manage business subscriptions of a certain type
- Trying to access a Partner API endpoint for which the API Client has not been enabled
- The monthly create quota for YELP_KNOWLEDGE subscriptions would be exceeded with the incoming request.
| code | description |
| ----- | ------------------ |
| PARTNER_ENDPOINT_DISABLED | You are trying to access a Partner API endpoint for which your API Client has not been enabled. Please reach out to partner-support@yelp.com for more information. |
| AUTHORIZATION_ERROR | Authorization Error |
| QUOTA_EXCEEDED | Exceeded the monthly create quota. |
'
content:
application/json:
schema:
$ref: '#/paths/~1subscriptions/get/responses/400/content/application~1json/schema'
examples:
Create Quota Exceeded:
value:
error:
code: QUOTA_EXCEEDED
description: Exceeded the monthly create quota.
Partner Endpoint Disabled:
value:
error:
code: PARTNER_ENDPOINT_DISABLED
description: You are trying to access a Partner API endpoint for which your API Client has not been enabled. Please reach out to partner-support@yelp.com for more information.
Authorization Error:
value:
error:
code: AUTHORIZATION_ERROR
description: Authorization Error
'429':
$ref: '#/paths/~1subscriptions/get/responses/429'
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
error:
type: object
required:
- code
- description
properties:
code:
type: string
description: The error code.
description:
type: string
description: The description of the error.
subscription_types:
type: object
description: Optional. Specified if some subscription types where managed successfully, while others failed.
required:
- succeeded
- failed
properties:
succeeded:
type: array
description: List of subscription types for which the Business Subscriptions were managed successfully.
items:
$ref: '#/paths/~1subscriptions/get/parameters/0/schema'
failed:
type: array
description: List of subscription types for which managing the Business Subscriptions failed.
items:
$ref: '#/paths/~1subscriptions/get/parameters/0/schema'
examples:
Internal Server Error:
value:
error:
code: INTERNAL_ERROR
description: Something went wrong internally, please try again later.
Partial Internal Error:
value:
error:
code: PARTIAL_INTERNAL_ERROR
description: Something went wrong internally, please try again later.
subscription_types:
succeeded:
- WEBHOOK
failed:
- LISTING_MANAGEMENT
- YELP_KNOWLEDGE
delete:
tags:
- Business Subscriptions
summary: Unsubscribe from businesses
description: 'Remove business subscriptions of the given types. Subscriptions are removed asynchronously after a request is accepted.
There is a maximum number of subscriptions with type YELP_KNOWLEDGE that can be removed yearly. To get this quota information please reach out to partner-support@yelp.com.
Example:
To remove business subscriptions of type LISTING_MANAGEMENT and YELP_KNOWLEDGE for two businesses, sent a DELETE request to the following URL:
https://api.yelp.com/v3/businesses/subscriptions
Containing the following request body:
```json
{
"subscription_types": ["LISTING_MANAGEMENT", "YELP_KNOWLEDGE"],
"business_ids": ["4U9kSBLuBDU391x6bxU-YA", "7w8SVwIEhxZ7jPnMUFYrng"]
}
```
**Note**: Each subscription type requires configuration by Yelp to access, please reach out to partner-support@yelp.com to configure access.'
operationId: remove_business_subscriptions
requestBody:
required: true
content:
application/json:
$ref: '#/paths/~1subscriptions/post/requestBody/content/application~1json'
responses:
'202':
description: Request accepted. The business subscriptions will be removed asynchronously
content:
application/json:
schema:
type: object
'400':
$ref: '#/paths/~1subscriptions/get/responses/400'
'401':
$ref: '#/paths/~1subscriptions/get/responses/401'
'403':
description: 'This error is returned in any of the following scenarios:
- The API key provided is not currently able to query this endpoint or manage business subscriptions of a certain type
- Trying to access a Partner API endpoint for which the API Client has not been enabled
- The yearly remove quota for YELP_KNOWLEDGE subscriptions would be exceeded with the incoming request.
| code | description |
| ----- | ------------------ |
| PARTNER_ENDPOINT_DISABLED | You are trying to access a Partner API endpoint for which your API Client has not been enabled. Please reach out to partner-support@yelp.com for more information. |
| AUTHORIZATION_ERROR | Authorization Error |
| QUOTA_EXCEEDED | Exceeded the yearly remove quota. |
'
content:
application/json:
schema:
$ref: '#/paths/~1subscriptions/get/responses/400/content/application~1json/schema'
examples:
Remove Quota Exceeded:
value:
error:
code: QUOTA_EXCEEDED
description: Exceeded the yearly remove quota.
Partner Endpoint Disabled:
value:
error:
code: PARTNER_ENDPOINT_DISABLED
description: You are trying to access a Partner API endpoint for which your API Client has not been enabled. Please reach out to partner-support@yelp.com for more information.
Authorization Error:
value:
error:
code: AUTHORIZATION_ERROR
description: Authorization Error
'429':
$ref: '#/paths/~1subscriptions/get/responses/429'
'500':
$ref: '#/paths/~1subscriptions/post/responses/500'
/subscriptions/{quota_subscription_type}/quota:
get:
tags:
- Business Subscriptions
summary: Get Quota
description: 'Get quota information for the given subscription type.
This includes the maximum number of subscriptions that can be active this month, the current total number of active subscriptions and the remaining amount that can be created this month.
To get quota information regarding the deletion of subscriptions, please reach out to partner-support@yelp.com'
operationId: get_business_subscriptions_quota
parameters:
- in: path
name: quota_subscription_type
description: Subscription Type for which the quota information is returned.
required: true
schema:
type: string
enum:
- YELP_KNOWLEDGE
responses:
'200':
description: Successfully fetched the quota information.
content:
application/json:
examples:
Result:
value:
total_subscriptions: 100
allowed_subscriptions: 125
remaining_subscriptions: 25
schema:
type: object
properties:
total_subscriptions:
type: integer
description: Number of currently active YELP_KNOWLEDGE subscriptions.
allowed_subscriptions:
type: integer
description: Number of total YELP_KNOWLEDGE subscriptions that can be created this month.
remaining_subscriptions:
type: integer
description: Number of remaining YELP_KNOWLEDGE subscriptions that can still be created this month.
required:
- total_subscriptions
- allowed_subscriptions
- remaining_subscriptions
'401':
$ref: '#/paths/~1subscriptions/get/responses/401'
'403':
$ref: '#/paths/~1subscriptions/get/responses/403'
'429':
$ref: '#/paths/~1subscriptions/get/responses/429'
'500':
$ref: '#/paths/~1subscriptions/get/responses/500'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'To authenticate API calls with the API Key, set the Authorization HTTP header value as `Bearer API_KEY`.
Example: `Bearer 23813239889e947efd3e787cc41b0b839f442a85c5bfd30bd4b9a85ec3a54d5cae4d52b37ff52e64deb9c83bd04883812a6cebde04f2f25752f31be0ac74b514`.
You can create or find your API Key at [yelp.com](https://www.yelp.com/developers/v3/manage_app).
'
x-provenance:
method: searched
source: https://docs.developer.yelp.com/reference
harvested: '2026-11-05'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://docs.developer.yelp.com/reference/create_business_subscriptions.md
- https://docs.developer.yelp.com/reference/get_business_subscriptions.md
- https://docs.developer.yelp.com/reference/get_business_subscriptions_quota.md
- https://docs.developer.yelp.com/reference/remove_business_subscriptions.md
merge:
pages: 4
deduped: 8
conflicts_kept_first: 0