# {% data variables.product.prodname\_marketplace %} 的 REST API 端点

使用 REST API 与 GitHub Marketplace 交互

## 关于 GitHub Marketplace

有关 GitHub Marketplace
的详细信息，请参阅 [GitHub市场](/zh/enterprise-cloud@latest/apps/github-marketplace)。

可以通过这些终结点查看哪些客户正在使用定价计划、客户的购买情况，以及帐户是否具有有效订阅。

### 使用存根端点进行测试

你可以[测试你的GitHub App](/zh/enterprise-cloud@latest/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/testing-your-app)（通过使用**存根数据**）。 存根数据是硬编码的假数据，不会根据实际订阅而更改。

要使用存根数据进行测试，请使用存根端点代替其对应的生产端点。 这样，就可以在列出GitHub AppsGitHub Marketplace之前测试 API 逻辑是否成功。

在部署 GitHub App 之前，请确保将存根终结点替换为生产终结点。

> \[!NOTE]
> 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.

## Get a subscription plan for an account

```
GET /marketplace_listing/accounts/{account_id}
```

Shows 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.
GitHub 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.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`account_id`** (integer) (required)
  account\_id parameter

### HTTP response status codes

* **200** - OK

* **401** - Requires authentication

* **404** - Not Found when the account has not purchased the listing

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/marketplace_listing/accounts/ACCOUNT_ID
```

**Response schema (Status: 200):**

* `url`: required, string
* `type`: required, string
* `id`: required, integer
* `login`: required, string
* `organization_billing_email`: string
* `email`: string or null
* `marketplace_pending_change`: object or null:
  * `is_installed`: boolean
  * `effective_date`: string
  * `unit_count`: integer or null
  * `id`: integer
  * `plan`: `Marketplace Listing Plan`:
    * `url`: required, string, format: uri
    * `accounts_url`: required, string, format: uri
    * `id`: required, integer
    * `number`: required, integer
    * `name`: required, string
    * `description`: required, string
    * `monthly_price_in_cents`: required, integer
    * `yearly_price_in_cents`: required, integer
    * `price_model`: required, string, enum: `FREE`, `FLAT_RATE`, `PER_UNIT`
    * `has_free_trial`: required, boolean
    * `unit_name`: required, string or null
    * `state`: required, string
    * `bullets`: required, array of string
* `marketplace_purchase`: required, object:
  * `billing_cycle`: string
  * `next_billing_date`: string or null
  * `is_installed`: boolean
  * `unit_count`: integer or null
  * `on_free_trial`: boolean
  * `free_trial_ends_on`: string or null
  * `updated_at`: string
  * `plan`: `Marketplace Listing Plan` (see above)

## List plans

```
GET /marketplace_listing/plans
```

Lists all plans that are part of your GitHub Enterprise Cloud Marketplace listing.
GitHub 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.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`per_page`** (integer)
  The number of results per page (max 100). For more information, see "Using pagination in the REST API."
  Default: `30`

* **`page`** (integer)
  The page number of the results to fetch. For more information, see "Using pagination in the REST API."
  Default: `1`

### HTTP response status codes

* **200** - OK

* **401** - Requires authentication

* **404** - Resource not found

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/marketplace_listing/plans
```

**Response schema (Status: 200):**

Array of `Marketplace Listing Plan`:

* `url`: required, string, format: uri
* `accounts_url`: required, string, format: uri
* `id`: required, integer
* `number`: required, integer
* `name`: required, string
* `description`: required, string
* `monthly_price_in_cents`: required, integer
* `yearly_price_in_cents`: required, integer
* `price_model`: required, string, enum: `FREE`, `FLAT_RATE`, `PER_UNIT`
* `has_free_trial`: required, boolean
* `unit_name`: required, string or null
* `state`: required, string
* `bullets`: required, array of string

## List accounts for a plan

```
GET /marketplace_listing/plans/{plan_id}/accounts
```

Returns 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.
GitHub 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.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`plan_id`** (integer) (required)
  The unique identifier of the plan.

* **`sort`** (string)
  The property to sort the results by.
  Default: `created`
  Can be one of: `created`, `updated`

* **`direction`** (string)
  To return the oldest accounts first, set to asc. Ignored without the sort parameter.
  Can be one of: `asc`, `desc`

* **`per_page`** (integer)
  The number of results per page (max 100). For more information, see "Using pagination in the REST API."
  Default: `30`

* **`page`** (integer)
  The page number of the results to fetch. For more information, see "Using pagination in the REST API."
  Default: `1`

### HTTP response status codes

* **200** - OK

* **401** - Requires authentication

* **404** - Resource not found

* **422** - Validation failed, or the endpoint has been spammed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/marketplace_listing/plans/PLAN_ID/accounts
```

**Response schema (Status: 200):**

Array of `Marketplace Purchase`:

* `url`: required, string
* `type`: required, string
* `id`: required, integer
* `login`: required, string
* `organization_billing_email`: string
* `email`: string or null
* `marketplace_pending_change`: object or null:
  * `is_installed`: boolean
  * `effective_date`: string
  * `unit_count`: integer or null
  * `id`: integer
  * `plan`: `Marketplace Listing Plan`:
    * `url`: required, string, format: uri
    * `accounts_url`: required, string, format: uri
    * `id`: required, integer
    * `number`: required, integer
    * `name`: required, string
    * `description`: required, string
    * `monthly_price_in_cents`: required, integer
    * `yearly_price_in_cents`: required, integer
    * `price_model`: required, string, enum: `FREE`, `FLAT_RATE`, `PER_UNIT`
    * `has_free_trial`: required, boolean
    * `unit_name`: required, string or null
    * `state`: required, string
    * `bullets`: required, array of string
* `marketplace_purchase`: required, object:
  * `billing_cycle`: string
  * `next_billing_date`: string or null
  * `is_installed`: boolean
  * `unit_count`: integer or null
  * `on_free_trial`: boolean
  * `free_trial_ends_on`: string or null
  * `updated_at`: string
  * `plan`: `Marketplace Listing Plan` (see above)

## Get a subscription plan for an account (stubbed)

```
GET /marketplace_listing/stubbed/accounts/{account_id}
```

Shows 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.
GitHub 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.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`account_id`** (integer) (required)
  account\_id parameter

### HTTP response status codes

* **200** - OK

* **401** - Requires authentication

* **404** - Not Found when the account has not purchased the listing

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/marketplace_listing/stubbed/accounts/ACCOUNT_ID
```

**Response schema (Status: 200):**

Same response schema as [Get a subscription plan for an account](#get-a-subscription-plan-for-an-account).

## List plans (stubbed)

```
GET /marketplace_listing/stubbed/plans
```

Lists all plans that are part of your GitHub Enterprise Cloud Marketplace listing.
GitHub 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.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`per_page`** (integer)
  The number of results per page (max 100). For more information, see "Using pagination in the REST API."
  Default: `30`

* **`page`** (integer)
  The page number of the results to fetch. For more information, see "Using pagination in the REST API."
  Default: `1`

### HTTP response status codes

* **200** - OK

* **401** - Requires authentication

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/marketplace_listing/stubbed/plans
```

**Response schema (Status: 200):**

Same response schema as [List plans](#list-plans).

## List accounts for a plan (stubbed)

```
GET /marketplace_listing/stubbed/plans/{plan_id}/accounts
```

Returns 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.
GitHub 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.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`plan_id`** (integer) (required)
  The unique identifier of the plan.

* **`sort`** (string)
  The property to sort the results by.
  Default: `created`
  Can be one of: `created`, `updated`

* **`direction`** (string)
  To return the oldest accounts first, set to asc. Ignored without the sort parameter.
  Can be one of: `asc`, `desc`

* **`per_page`** (integer)
  The number of results per page (max 100). For more information, see "Using pagination in the REST API."
  Default: `30`

* **`page`** (integer)
  The page number of the results to fetch. For more information, see "Using pagination in the REST API."
  Default: `1`

### HTTP response status codes

* **200** - OK

* **401** - Requires authentication

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/marketplace_listing/stubbed/plans/PLAN_ID/accounts
```

**Response schema (Status: 200):**

Same response schema as [List accounts for a plan](#list-accounts-for-a-plan).

## List subscriptions for the authenticated user

```
GET /user/marketplace_purchases
```

Lists the active subscriptions for the authenticated user.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`per_page`** (integer)
  The number of results per page (max 100). For more information, see "Using pagination in the REST API."
  Default: `30`

* **`page`** (integer)
  The page number of the results to fetch. For more information, see "Using pagination in the REST API."
  Default: `1`

### HTTP response status codes

* **200** - OK

* **304** - Not modified

* **401** - Requires authentication

* **404** - Resource not found

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/user/marketplace_purchases
```

**Response schema (Status: 200):**

Array of `User Marketplace Purchase`:

* `billing_cycle`: required, string
* `next_billing_date`: required, string or null, format: date-time
* `unit_count`: required, integer or null
* `on_free_trial`: required, boolean
* `free_trial_ends_on`: required, string or null, format: date-time
* `updated_at`: required, string or null, format: date-time
* `account`: required, `Marketplace Account`:
  * `url`: required, string, format: uri
  * `id`: required, integer
  * `type`: required, string
  * `node_id`: string
  * `login`: required, string
  * `email`: string or null, format: email
  * `organization_billing_email`: string or null, format: email
* `plan`: required, `Marketplace Listing Plan`:
  * `url`: required, string, format: uri
  * `accounts_url`: required, string, format: uri
  * `id`: required, integer
  * `number`: required, integer
  * `name`: required, string
  * `description`: required, string
  * `monthly_price_in_cents`: required, integer
  * `yearly_price_in_cents`: required, integer
  * `price_model`: required, string, enum: `FREE`, `FLAT_RATE`, `PER_UNIT`
  * `has_free_trial`: required, boolean
  * `unit_name`: required, string or null
  * `state`: required, string
  * `bullets`: required, array of string

## List subscriptions for the authenticated user (stubbed)

```
GET /user/marketplace_purchases/stubbed
```

Lists the active subscriptions for the authenticated user.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`per_page`** (integer)
  The number of results per page (max 100). For more information, see "Using pagination in the REST API."
  Default: `30`

* **`page`** (integer)
  The page number of the results to fetch. For more information, see "Using pagination in the REST API."
  Default: `1`

### HTTP response status codes

* **200** - OK

* **304** - Not modified

* **401** - Requires authentication

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/user/marketplace_purchases/stubbed
```

**Response schema (Status: 200):**

Same response schema as [List subscriptions for the authenticated user](#list-subscriptions-for-the-authenticated-user).