{"meta":{"title":"GitHub Marketplace 的 REST API 终结点","intro":"使用 REST API 与 GitHub Marketplace 交互","product":"REST API","breadcrumbs":[{"href":"/zh/rest","title":"REST API"},{"href":"/zh/rest/apps","title":"应用"},{"href":"/zh/rest/apps/marketplace","title":"Marketplace"}],"documentType":"article"},"body":"# {% data variables.product.prodname\\_marketplace %} 的 REST API 终结点\n\n使用 REST API 与 GitHub Marketplace 交互\n\n## 关于 GitHub Marketplace\n\n有关 GitHub Marketplace\n的详细信息，请参阅 [GitHub市场](/zh/apps/publishing-apps-to-github-marketplace)。\n\n可以通过这些终结点查看哪些客户正在使用定价计划、客户的购买情况，以及帐户是否具有有效订阅。\n\n### 使用存根端点进行测试\n\n可以使用[模拟数据](/zh/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/testing-your-app)来**测试你的 GitHub App**。 存根数据是硬编码的假数据，不会根据实际订阅而更改。\n\n要使用存根数据进行测试，请使用存根端点代替其对应的生产端点。 这允许你在将 GitHub Apps 列入 GitHub Marketplace\n之前，测试 API 逻辑是否成功。\n\n在部署 GitHub App 之前，确保将存根终结点替换为生产终结点。\n\n> \\[!NOTE]\n> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2026-03-10`. Curl examples below omit these standard headers for brevity.\n\n## Get a subscription plan for an account\n\n```\nGET /marketplace_listing/accounts/{account_id}\n```\n\nShows whether the user or organization account actively subscribes to a plan listed by the authenticated GitHub App. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.\nGitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`account_id`** (integer) (required)\n  account\\_id parameter\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **401** - Requires authentication\n\n* **404** - Not Found when the account has not purchased the listing\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/marketplace_listing/accounts/ACCOUNT_ID\n```\n\n**Response schema (Status: 200):**\n\n* `url`: required, string\n* `type`: required, string\n* `id`: required, integer\n* `login`: required, string\n* `organization_billing_email`: string\n* `email`: string or null\n* `marketplace_pending_change`: object or null:\n  * `is_installed`: boolean\n  * `effective_date`: string\n  * `unit_count`: integer or null\n  * `id`: integer\n  * `plan`: `Marketplace Listing Plan`:\n    * `url`: required, string, format: uri\n    * `accounts_url`: required, string, format: uri\n    * `id`: required, integer\n    * `number`: required, integer\n    * `name`: required, string\n    * `description`: required, string\n    * `monthly_price_in_cents`: required, integer\n    * `yearly_price_in_cents`: required, integer\n    * `price_model`: required, string, enum: `FREE`, `FLAT_RATE`, `PER_UNIT`\n    * `has_free_trial`: required, boolean\n    * `unit_name`: required, string or null\n    * `state`: required, string\n    * `bullets`: required, array of string\n* `marketplace_purchase`: required, object:\n  * `billing_cycle`: string\n  * `next_billing_date`: string or null\n  * `is_installed`: boolean\n  * `unit_count`: integer or null\n  * `on_free_trial`: boolean\n  * `free_trial_ends_on`: string or null\n  * `updated_at`: string\n  * `plan`: `Marketplace Listing Plan`:\n    * `url`: required, string, format: uri\n    * `accounts_url`: required, string, format: uri\n    * `id`: required, integer\n    * `number`: required, integer\n    * `name`: required, string\n    * `description`: required, string\n    * `monthly_price_in_cents`: required, integer\n    * `yearly_price_in_cents`: required, integer\n    * `price_model`: required, string, enum: `FREE`, `FLAT_RATE`, `PER_UNIT`\n    * `has_free_trial`: required, boolean\n    * `unit_name`: required, string or null\n    * `state`: required, string\n    * `bullets`: required, array of string\n\n## List plans\n\n```\nGET /marketplace_listing/plans\n```\n\nLists all plans that are part of your GitHub Marketplace listing.\nGitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`per_page`** (integer)\n  The number of results per page (max 100). For more information, see \"Using pagination in the REST API.\"\n  Default: `30`\n\n* **`page`** (integer)\n  The page number of the results to fetch. For more information, see \"Using pagination in the REST API.\"\n  Default: `1`\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **401** - Requires authentication\n\n* **404** - Resource not found\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/marketplace_listing/plans\n```\n\n**Response schema (Status: 200):**\n\nArray of `Marketplace Listing Plan`:\n\n* `url`: required, string, format: uri\n* `accounts_url`: required, string, format: uri\n* `id`: required, integer\n* `number`: required, integer\n* `name`: required, string\n* `description`: required, string\n* `monthly_price_in_cents`: required, integer\n* `yearly_price_in_cents`: required, integer\n* `price_model`: required, string, enum: `FREE`, `FLAT_RATE`, `PER_UNIT`\n* `has_free_trial`: required, boolean\n* `unit_name`: required, string or null\n* `state`: required, string\n* `bullets`: required, array of string\n\n## List accounts for a plan\n\n```\nGET /marketplace_listing/plans/{plan_id}/accounts\n```\n\nReturns user and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.\nGitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`plan_id`** (integer) (required)\n  The unique identifier of the plan.\n\n* **`sort`** (string)\n  The property to sort the results by.\n  Default: `created`\n  Can be one of: `created`, `updated`\n\n* **`direction`** (string)\n  To return the oldest accounts first, set to asc. Ignored without the sort parameter.\n  Can be one of: `asc`, `desc`\n\n* **`per_page`** (integer)\n  The number of results per page (max 100). For more information, see \"Using pagination in the REST API.\"\n  Default: `30`\n\n* **`page`** (integer)\n  The page number of the results to fetch. For more information, see \"Using pagination in the REST API.\"\n  Default: `1`\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **401** - Requires authentication\n\n* **404** - Resource not found\n\n* **422** - Validation failed, or the endpoint has been spammed.\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/marketplace_listing/plans/PLAN_ID/accounts\n```\n\n**Response schema (Status: 200):**\n\nArray of `Marketplace Purchase`:\n\n* `url`: required, string\n* `type`: required, string\n* `id`: required, integer\n* `login`: required, string\n* `organization_billing_email`: string\n* `email`: string or null\n* `marketplace_pending_change`: object or null:\n  * `is_installed`: boolean\n  * `effective_date`: string\n  * `unit_count`: integer or null\n  * `id`: integer\n  * `plan`: `Marketplace Listing Plan`:\n    * `url`: required, string, format: uri\n    * `accounts_url`: required, string, format: uri\n    * `id`: required, integer\n    * `number`: required, integer\n    * `name`: required, string\n    * `description`: required, string\n    * `monthly_price_in_cents`: required, integer\n    * `yearly_price_in_cents`: required, integer\n    * `price_model`: required, string, enum: `FREE`, `FLAT_RATE`, `PER_UNIT`\n    * `has_free_trial`: required, boolean\n    * `unit_name`: required, string or null\n    * `state`: required, string\n    * `bullets`: required, array of string\n* `marketplace_purchase`: required, object:\n  * `billing_cycle`: string\n  * `next_billing_date`: string or null\n  * `is_installed`: boolean\n  * `unit_count`: integer or null\n  * `on_free_trial`: boolean\n  * `free_trial_ends_on`: string or null\n  * `updated_at`: string\n  * `plan`: `Marketplace Listing Plan`:\n    * `url`: required, string, format: uri\n    * `accounts_url`: required, string, format: uri\n    * `id`: required, integer\n    * `number`: required, integer\n    * `name`: required, string\n    * `description`: required, string\n    * `monthly_price_in_cents`: required, integer\n    * `yearly_price_in_cents`: required, integer\n    * `price_model`: required, string, enum: `FREE`, `FLAT_RATE`, `PER_UNIT`\n    * `has_free_trial`: required, boolean\n    * `unit_name`: required, string or null\n    * `state`: required, string\n    * `bullets`: required, array of string\n\n## Get a subscription plan for an account (stubbed)\n\n```\nGET /marketplace_listing/stubbed/accounts/{account_id}\n```\n\nShows whether the user or organization account actively subscribes to a plan listed by the authenticated GitHub App. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.\nGitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`account_id`** (integer) (required)\n  account\\_id parameter\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **401** - Requires authentication\n\n* **404** - Not Found when the account has not purchased the listing\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/marketplace_listing/stubbed/accounts/ACCOUNT_ID\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [Get a subscription plan for an account](#get-a-subscription-plan-for-an-account).\n\n## List plans (stubbed)\n\n```\nGET /marketplace_listing/stubbed/plans\n```\n\nLists all plans that are part of your GitHub Marketplace listing.\nGitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`per_page`** (integer)\n  The number of results per page (max 100). For more information, see \"Using pagination in the REST API.\"\n  Default: `30`\n\n* **`page`** (integer)\n  The page number of the results to fetch. For more information, see \"Using pagination in the REST API.\"\n  Default: `1`\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **401** - Requires authentication\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/marketplace_listing/stubbed/plans\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [List plans](#list-plans).\n\n## List accounts for a plan (stubbed)\n\n```\nGET /marketplace_listing/stubbed/plans/{plan_id}/accounts\n```\n\nReturns repository and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.\nGitHub Apps must use a JWT to access this endpoint. OAuth apps must use basic authentication with their client ID and client secret to access this endpoint.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`plan_id`** (integer) (required)\n  The unique identifier of the plan.\n\n* **`sort`** (string)\n  The property to sort the results by.\n  Default: `created`\n  Can be one of: `created`, `updated`\n\n* **`direction`** (string)\n  To return the oldest accounts first, set to asc. Ignored without the sort parameter.\n  Can be one of: `asc`, `desc`\n\n* **`per_page`** (integer)\n  The number of results per page (max 100). For more information, see \"Using pagination in the REST API.\"\n  Default: `30`\n\n* **`page`** (integer)\n  The page number of the results to fetch. For more information, see \"Using pagination in the REST API.\"\n  Default: `1`\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **401** - Requires authentication\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/marketplace_listing/stubbed/plans/PLAN_ID/accounts\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [List accounts for a plan](#list-accounts-for-a-plan).\n\n## List subscriptions for the authenticated user\n\n```\nGET /user/marketplace_purchases\n```\n\nLists the active subscriptions for the authenticated user.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`per_page`** (integer)\n  The number of results per page (max 100). For more information, see \"Using pagination in the REST API.\"\n  Default: `30`\n\n* **`page`** (integer)\n  The page number of the results to fetch. For more information, see \"Using pagination in the REST API.\"\n  Default: `1`\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **304** - Not modified\n\n* **401** - Requires authentication\n\n* **404** - Resource not found\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/user/marketplace_purchases\n```\n\n**Response schema (Status: 200):**\n\nArray of `User Marketplace Purchase`:\n\n* `billing_cycle`: required, string\n* `next_billing_date`: required, string or null, format: date-time\n* `unit_count`: required, integer or null\n* `on_free_trial`: required, boolean\n* `free_trial_ends_on`: required, string or null, format: date-time\n* `updated_at`: required, string or null, format: date-time\n* `account`: required, `Marketplace Account`:\n  * `url`: required, string, format: uri\n  * `id`: required, integer\n  * `type`: required, string\n  * `node_id`: string\n  * `login`: required, string\n  * `email`: string or null, format: email\n  * `organization_billing_email`: string or null, format: email\n* `plan`: required, `Marketplace Listing Plan`:\n  * `url`: required, string, format: uri\n  * `accounts_url`: required, string, format: uri\n  * `id`: required, integer\n  * `number`: required, integer\n  * `name`: required, string\n  * `description`: required, string\n  * `monthly_price_in_cents`: required, integer\n  * `yearly_price_in_cents`: required, integer\n  * `price_model`: required, string, enum: `FREE`, `FLAT_RATE`, `PER_UNIT`\n  * `has_free_trial`: required, boolean\n  * `unit_name`: required, string or null\n  * `state`: required, string\n  * `bullets`: required, array of string\n\n## List subscriptions for the authenticated user (stubbed)\n\n```\nGET /user/marketplace_purchases/stubbed\n```\n\nLists the active subscriptions for the authenticated user.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`per_page`** (integer)\n  The number of results per page (max 100). For more information, see \"Using pagination in the REST API.\"\n  Default: `30`\n\n* **`page`** (integer)\n  The page number of the results to fetch. For more information, see \"Using pagination in the REST API.\"\n  Default: `1`\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **304** - Not modified\n\n* **401** - Requires authentication\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/user/marketplace_purchases/stubbed\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [List subscriptions for the authenticated user](#list-subscriptions-for-the-authenticated-user)."}