REST API endpoints for GitHub Marketplace

About GitHub Marketplace

For more information about GitHub Marketplace, see "GitHub Marketplace."

These endpoints allow you to see which customers are using a pricing plan, see a customer's purchases, and see if an account has an active subscription.

Testing with stubbed endpoints

You can test your GitHub App with stubbed data. Stubbed data is hard-coded, fake data that will not change based on actual subscriptions.

To test with stubbed data, use a stubbed endpoint in place of its production counterpart. This allows you to test whether the API logic succeeds before listing GitHub Apps on GitHub Marketplace.

Make sure to replace stubbed endpoints with production endpoints before deploying your GitHub App.

Get a subscription plan for an account

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.

Fine-grained access tokens for "Get a subscription plan for an account"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Get a subscription plan for an account"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`account_id` integer Required account_id parameter

HTTP response status codes for "Get a subscription plan for an account"

Status code	Description
`200`	OK
`401`	Requires authentication
`404`	Not Found when the account has not purchased the listing

Code samples for "Get a subscription plan for an account"

Request example

get/marketplace_listing/accounts/{account_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/marketplace_listing/accounts/ACCOUNT_ID

Response

Status: 200

{
  "url": "https://api.github.com/orgs/github",
  "type": "Organization",
  "id": 4,
  "login": "github",
  "organization_billing_email": "billing@github.com",
  "email": "billing@github.com",
  "marketplace_pending_change": {
    "effective_date": "2017-11-11T00:00:00Z",
    "unit_count": null,
    "id": 77,
    "plan": {
      "url": "https://api.github.com/marketplace_listing/plans/1111",
      "accounts_url": "https://api.github.com/marketplace_listing/plans/1111/accounts",
      "id": 1111,
      "number": 2,
      "name": "Startup",
      "description": "A professional-grade CI solution",
      "monthly_price_in_cents": 699,
      "yearly_price_in_cents": 7870,
      "price_model": "FLAT_RATE",
      "has_free_trial": true,
      "state": "published",
      "unit_name": null,
      "bullets": [
        "Up to 10 private repositories",
        "3 concurrent builds"
      ]
    }
  },
  "marketplace_purchase": {
    "billing_cycle": "monthly",
    "next_billing_date": "2017-11-11T00:00:00Z",
    "unit_count": null,
    "on_free_trial": true,
    "free_trial_ends_on": "2017-11-11T00:00:00Z",
    "updated_at": "2017-11-02T01:12:12Z",
    "plan": {
      "url": "https://api.github.com/marketplace_listing/plans/1313",
      "accounts_url": "https://api.github.com/marketplace_listing/plans/1313/accounts",
      "id": 1313,
      "number": 3,
      "name": "Pro",
      "description": "A professional-grade CI solution",
      "monthly_price_in_cents": 1099,
      "yearly_price_in_cents": 11870,
      "price_model": "FLAT_RATE",
      "has_free_trial": true,
      "unit_name": null,
      "state": "published",
      "bullets": [
        "Up to 25 private repositories",
        "11 concurrent builds"
      ]
    }
  }
}

List plans

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

Fine-grained access tokens for "List plans"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List plans"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Query parameters
Name, Type, Description
`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 for "List plans"

Status code	Description
`200`	OK
`401`	Requires authentication
`404`	Resource not found

Code samples for "List plans"

Request example

get/marketplace_listing/plans

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/marketplace_listing/plans

Response

Status: 200

[
  {
    "url": "https://api.github.com/marketplace_listing/plans/1313",
    "accounts_url": "https://api.github.com/marketplace_listing/plans/1313/accounts",
    "id": 1313,
    "number": 3,
    "name": "Pro",
    "description": "A professional-grade CI solution",
    "monthly_price_in_cents": 1099,
    "yearly_price_in_cents": 11870,
    "price_model": "FLAT_RATE",
    "has_free_trial": true,
    "unit_name": null,
    "state": "published",
    "bullets": [
      "Up to 25 private repositories",
      "11 concurrent builds"
    ]
  }
]

List accounts for a plan

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.

Fine-grained access tokens for "List accounts for a plan"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List accounts for a plan"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`plan_id` integer Required The unique identifier of the plan.

Query parameters
Name, Type, Description
`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 for "List accounts for a plan"

Status code	Description
`200`	OK
`401`	Requires authentication
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "List accounts for a plan"

Request example

get/marketplace_listing/plans/{plan_id}/accounts

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/marketplace_listing/plans/PLAN_ID/accounts

Response

Status: 200

[
  {
    "url": "https://api.github.com/orgs/github",
    "type": "Organization",
    "id": 4,
    "login": "github",
    "organization_billing_email": "billing@github.com",
    "marketplace_pending_change": {
      "effective_date": "2017-11-11T00:00:00Z",
      "unit_count": null,
      "id": 77,
      "plan": {
        "url": "https://api.github.com/marketplace_listing/plans/1111",
        "accounts_url": "https://api.github.com/marketplace_listing/plans/1111/accounts",
        "id": 1111,
        "number": 2,
        "name": "Startup",
        "description": "A professional-grade CI solution",
        "monthly_price_in_cents": 699,
        "yearly_price_in_cents": 7870,
        "price_model": "FLAT_RATE",
        "has_free_trial": true,
        "state": "published",
        "unit_name": null,
        "bullets": [
          "Up to 10 private repositories",
          "3 concurrent builds"
        ]
      }
    },
    "marketplace_purchase": {
      "billing_cycle": "monthly",
      "next_billing_date": "2017-11-11T00:00:00Z",
      "unit_count": null,
      "on_free_trial": true,
      "free_trial_ends_on": "2017-11-11T00:00:00Z",
      "updated_at": "2017-11-02T01:12:12Z",
      "plan": {
        "url": "https://api.github.com/marketplace_listing/plans/1313",
        "accounts_url": "https://api.github.com/marketplace_listing/plans/1313/accounts",
        "id": 1313,
        "number": 3,
        "name": "Pro",
        "description": "A professional-grade CI solution",
        "monthly_price_in_cents": 1099,
        "yearly_price_in_cents": 11870,
        "price_model": "FLAT_RATE",
        "has_free_trial": true,
        "unit_name": null,
        "state": "published",
        "bullets": [
          "Up to 25 private repositories",
          "11 concurrent builds"
        ]
      }
    }
  }
]

Get a subscription plan for an account (stubbed)

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.

Fine-grained access tokens for "Get a subscription plan for an account (stubbed)"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Get a subscription plan for an account (stubbed)"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`account_id` integer Required account_id parameter

HTTP response status codes for "Get a subscription plan for an account (stubbed)"

Status code	Description
`200`	OK
`401`	Requires authentication
`404`	Not Found when the account has not purchased the listing

Code samples for "Get a subscription plan for an account (stubbed)"

Request example

get/marketplace_listing/stubbed/accounts/{account_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/marketplace_listing/stubbed/accounts/ACCOUNT_ID

Response

Status: 200

{
  "url": "https://api.github.com/orgs/github",
  "type": "Organization",
  "id": 4,
  "login": "github",
  "organization_billing_email": "billing@github.com",
  "email": "billing@github.com",
  "marketplace_pending_change": {
    "effective_date": "2017-11-11T00:00:00Z",
    "unit_count": null,
    "id": 77,
    "plan": {
      "url": "https://api.github.com/marketplace_listing/plans/1111",
      "accounts_url": "https://api.github.com/marketplace_listing/plans/1111/accounts",
      "id": 1111,
      "number": 2,
      "name": "Startup",
      "description": "A professional-grade CI solution",
      "monthly_price_in_cents": 699,
      "yearly_price_in_cents": 7870,
      "price_model": "FLAT_RATE",
      "has_free_trial": true,
      "state": "published",
      "unit_name": null,
      "bullets": [
        "Up to 10 private repositories",
        "3 concurrent builds"
      ]
    }
  },
  "marketplace_purchase": {
    "billing_cycle": "monthly",
    "next_billing_date": "2017-11-11T00:00:00Z",
    "unit_count": null,
    "on_free_trial": true,
    "free_trial_ends_on": "2017-11-11T00:00:00Z",
    "updated_at": "2017-11-02T01:12:12Z",
    "plan": {
      "url": "https://api.github.com/marketplace_listing/plans/1313",
      "accounts_url": "https://api.github.com/marketplace_listing/plans/1313/accounts",
      "id": 1313,
      "number": 3,
      "name": "Pro",
      "description": "A professional-grade CI solution",
      "monthly_price_in_cents": 1099,
      "yearly_price_in_cents": 11870,
      "price_model": "FLAT_RATE",
      "has_free_trial": true,
      "unit_name": null,
      "state": "published",
      "bullets": [
        "Up to 25 private repositories",
        "11 concurrent builds"
      ]
    }
  }
}

List plans (stubbed)

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

Fine-grained access tokens for "List plans (stubbed)"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List plans (stubbed)"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Query parameters
Name, Type, Description
`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 for "List plans (stubbed)"

Status code	Description
`200`	OK
`401`	Requires authentication

Code samples for "List plans (stubbed)"

Request example

get/marketplace_listing/stubbed/plans

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/marketplace_listing/stubbed/plans

Response

Status: 200

[
  {
    "url": "https://api.github.com/marketplace_listing/plans/1313",
    "accounts_url": "https://api.github.com/marketplace_listing/plans/1313/accounts",
    "id": 1313,
    "number": 3,
    "name": "Pro",
    "description": "A professional-grade CI solution",
    "monthly_price_in_cents": 1099,
    "yearly_price_in_cents": 11870,
    "price_model": "FLAT_RATE",
    "has_free_trial": true,
    "unit_name": null,
    "state": "published",
    "bullets": [
      "Up to 25 private repositories",
      "11 concurrent builds"
    ]
  }
]

List accounts for a plan (stubbed)

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.

Fine-grained access tokens for "List accounts for a plan (stubbed)"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List accounts for a plan (stubbed)"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`plan_id` integer Required The unique identifier of the plan.

Query parameters
Name, Type, Description
`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 for "List accounts for a plan (stubbed)"

Status code	Description
`200`	OK
`401`	Requires authentication

Code samples for "List accounts for a plan (stubbed)"

Request example

get/marketplace_listing/stubbed/plans/{plan_id}/accounts

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/marketplace_listing/stubbed/plans/PLAN_ID/accounts

Response

Status: 200

[
  {
    "url": "https://api.github.com/orgs/github",
    "type": "Organization",
    "id": 4,
    "login": "github",
    "organization_billing_email": "billing@github.com",
    "marketplace_pending_change": {
      "effective_date": "2017-11-11T00:00:00Z",
      "unit_count": null,
      "id": 77,
      "plan": {
        "url": "https://api.github.com/marketplace_listing/plans/1111",
        "accounts_url": "https://api.github.com/marketplace_listing/plans/1111/accounts",
        "id": 1111,
        "number": 2,
        "name": "Startup",
        "description": "A professional-grade CI solution",
        "monthly_price_in_cents": 699,
        "yearly_price_in_cents": 7870,
        "price_model": "FLAT_RATE",
        "has_free_trial": true,
        "state": "published",
        "unit_name": null,
        "bullets": [
          "Up to 10 private repositories",
          "3 concurrent builds"
        ]
      }
    },
    "marketplace_purchase": {
      "billing_cycle": "monthly",
      "next_billing_date": "2017-11-11T00:00:00Z",
      "unit_count": null,
      "on_free_trial": true,
      "free_trial_ends_on": "2017-11-11T00:00:00Z",
      "updated_at": "2017-11-02T01:12:12Z",
      "plan": {
        "url": "https://api.github.com/marketplace_listing/plans/1313",
        "accounts_url": "https://api.github.com/marketplace_listing/plans/1313/accounts",
        "id": 1313,
        "number": 3,
        "name": "Pro",
        "description": "A professional-grade CI solution",
        "monthly_price_in_cents": 1099,
        "yearly_price_in_cents": 11870,
        "price_model": "FLAT_RATE",
        "has_free_trial": true,
        "unit_name": null,
        "state": "published",
        "bullets": [
          "Up to 25 private repositories",
          "11 concurrent builds"
        ]
      }
    }
  }
]

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Query parameters
Name, Type, Description
`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 for "List subscriptions for the authenticated user"

Status code	Description
`200`	OK
`304`	Not modified
`401`	Requires authentication
`404`	Resource not found

Code samples for "List subscriptions for the authenticated user"

Request example

get/user/marketplace_purchases

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/user/marketplace_purchases

Response

Status: 200

[
  {
    "billing_cycle": "monthly",
    "next_billing_date": "2017-11-11T00:00:00Z",
    "unit_count": null,
    "on_free_trial": true,
    "free_trial_ends_on": "2017-11-11T00:00:00Z",
    "updated_at": "2017-11-02T01:12:12Z",
    "account": {
      "login": "github",
      "id": 4,
      "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
      "url": "https://api.github.com/orgs/github",
      "email": null,
      "organization_billing_email": "billing@github.com",
      "type": "Organization"
    },
    "plan": {
      "url": "https://api.github.com/marketplace_listing/plans/1313",
      "accounts_url": "https://api.github.com/marketplace_listing/plans/1313/accounts",
      "id": 1313,
      "number": 3,
      "name": "Pro",
      "description": "A professional-grade CI solution",
      "monthly_price_in_cents": 1099,
      "yearly_price_in_cents": 11870,
      "price_model": "FLAT_RATE",
      "has_free_trial": true,
      "unit_name": null,
      "state": "published",
      "bullets": [
        "Up to 25 private repositories",
        "11 concurrent builds"
      ]
    }
  }
]

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Query parameters
Name, Type, Description
`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 for "List subscriptions for the authenticated user (stubbed)"

Status code	Description
`200`	OK
`304`	Not modified
`401`	Requires authentication

Code samples for "List subscriptions for the authenticated user (stubbed)"

Request example

get/user/marketplace_purchases/stubbed

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/user/marketplace_purchases/stubbed

Response

Status: 200

[
  {
    "billing_cycle": "monthly",
    "next_billing_date": "2017-11-11T00:00:00Z",
    "unit_count": null,
    "on_free_trial": true,
    "free_trial_ends_on": "2017-11-11T00:00:00Z",
    "updated_at": "2017-11-02T01:12:12Z",
    "account": {
      "login": "github",
      "id": 4,
      "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
      "url": "https://api.github.com/orgs/github",
      "email": null,
      "organization_billing_email": "billing@github.com",
      "type": "Organization"
    },
    "plan": {
      "url": "https://api.github.com/marketplace_listing/plans/1313",
      "accounts_url": "https://api.github.com/marketplace_listing/plans/1313/accounts",
      "id": 1313,
      "number": 3,
      "name": "Pro",
      "description": "A professional-grade CI solution",
      "monthly_price_in_cents": 1099,
      "yearly_price_in_cents": 11870,
      "price_model": "FLAT_RATE",
      "has_free_trial": true,
      "unit_name": null,
      "state": "published",
      "bullets": [
        "Up to 25 private repositories",
        "11 concurrent builds"
      ]
    }
  }
]