--- agentTools: projectIndex: https://docs.developer.yelp.com/llms.txt --- # Get Business Subscriptions 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. [block:callout] { "type": "info", "body": "This endpoint is part of the Business Subscriptions API, visit [Business Subscriptions API](https://docs.developer.yelp.com/docs/business-subscriptions-api) to learn more." } [/block] # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "Business Subscriptions", "version": "1.0" }, "servers": [ { "url": "https://api.yelp.com/v3/businesses/" } ], "security": [ { "bearerAuth": [] } ], "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`.\n\nExample: `Bearer 23813239889e947efd3e787cc41b0b839f442a85c5bfd30bd4b9a85ec3a54d5cae4d52b37ff52e64deb9c83bd04883812a6cebde04f2f25752f31be0ac74b514`.\n\nYou can create or find your API Key at [yelp.com](https://www.yelp.com/developers/v3/manage_app).\n" } } }, "paths": { "/subscriptions": { "get": { "tags": [ "Business Subscriptions" ], "summary": "Get Business Subscriptions", "description": "Retrieve a paginated list of business subscriptions for a given subscription type.\n\nExample:\nTo fetch the first 100 business subscriptions of type WEBHOOK, sent a GET request to the following URL:\nhttps://api.yelp.com/v3/businesses/subscriptions?subscription_type=WEBHOOK\n\nFor the above request a successful GET call will return at most 100 business subscriptions with the following response body:\n\n```json\n{\n \"total\": 2,\n \"offset\": 0,\n \"limit\": 100,\n \"subscription_type\": \"WEBHOOK\",\n \"subscriptions\": [\n {\"business_id\": \"4U9kSBLuBDU391x6bxU-YA\", \"subscribed_at\": \"2022-12-10T09:50:00+00\"},\n {\"business_id\": \"7w8SVwIEhxZ7jPnMUFYrng\", \"subscribed_at\": \"2022-12-10T10:52:30+00\"},\n ]\n}\n```\n\n**Note**: Each subscription type requires configuration by Yelp to access, please reach out to partner-support@yelp.com to configure access.\n", "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.\n\n| code | description |\n| ------------- | ------------- |\n| UNAUTHORIZED_API_KEY | The API key provided is not currently able to query this endpoint. |\n| TOKEN_INVALID | Invalid API key or authorization header. |\n", "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:\n- The API key provided is not currently able to query this endpoint or manage business subscriptions of a certain type\n- Trying to access a Partner API endpoint for which the API Client has not been enabled\n\n| code | description |\n| ----- | ------------------ |\n| 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. |\n| AUTHORIZATION_ERROR | Authorization Error |\n", "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.\nThere is a maximum number of subscriptions with type YELP_KNOWLEDGE that can be active in the current month. Use [Get Quota](https://docs.developer.yelp.com/reference/get_business_subscriptions_quota) to retrieve the quota information.\n\nExample:\nTo create business subscriptions of type LISTING_MANAGEMENT and YELP_KNOWLEDGE for two businesses, sent a POST request to the following URL:\nhttps://api.yelp.com/v3/businesses/subscriptions\n\nContaining the following request body:\n```json\n{\n \"subscription_types\": [\"LISTING_MANAGEMENT\", \"YELP_KNOWLEDGE\"],\n \"business_ids\": [\"4U9kSBLuBDU391x6bxU-YA\", \"7w8SVwIEhxZ7jPnMUFYrng\"]\n}\n```\n\n**Note**: Each subscription type requires configuration by Yelp to access, please reach out to partner-support@yelp.com to configure access.\n", "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:\n- The API key provided is not currently able to query this endpoint or manage business subscriptions of a certain type\n- Trying to access a Partner API endpoint for which the API Client has not been enabled\n- The monthly create quota for YELP_KNOWLEDGE subscriptions would be exceeded with the incoming request.\n\n| code | description |\n| ----- | ------------------ |\n| 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. |\n| AUTHORIZATION_ERROR | Authorization Error |\n| QUOTA_EXCEEDED | Exceeded the monthly create quota. |\n", "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" ] } } } } } } } } } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": false, "samples-enabled": true }, "_id": { "buffer": { "0": 99, "1": 155, "2": 3, "3": 89, "4": 237, "5": 206, "6": 159, "7": 0, "8": 15, "9": 218, "10": 27, "11": 156 } } } ````