GitHub Marketplace

Note: The The GitHub Marketplace API on GitHub is currently available for developers to preview. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.valkyrie-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

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

Note: This preview includes methods for testing with stubbed data. Stubbed data is fake data that's useful for testing your GitHub Apps. Stubbed data is hard-coded and 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 API logic succeeds before listing GitHub Apps on GitHub Marketplace.

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

Endpoints for /marketplace_listing/* and /user/marketplace_purchases are only accessible by OAuth Apps using client_id and secret basic authentication or by GitHub Apps using a JWT.

List all plans for your Marketplace listing

Note: The The GitHub Marketplace API on GitHub is currently available for developers to preview. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.valkyrie-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

GET /marketplace_listing/plans

Stubbed endpoint

GET /marketplace_listing/stubbed/plans

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "url": "https://api.github.com/marketplace_listing/plans/9",
    "accounts_url": "https://api.github.com/marketplace_listing/plans/9/accounts",
    "id": 9,
    "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,
    "bullets": [
      "This is the first bullet of the plan",
      "This is the second bullet of the plan"
    ]
  }
]

List all GitHub accounts (user or organization) on a specific plan

Note: The The GitHub Marketplace API on GitHub is currently available for developers to preview. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.valkyrie-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

Returns any accounts associated with a 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.

GET /marketplace_listing/plans/:id/accounts

Stubbed endpoint

GET /marketplace_listing/stubbed/plans/:id/accounts

Parameters

Name Type Description
sort string Sorts the GitHub accounts by the date they were created or last updated. Can be one of created or updated. Default: created
direction string To return the oldest accounts first, set to asc. Can be one of asc or desc. Ignored without the sort parameter.

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "url": "https://api.github.com/orgs/github",
    "type": "Organization",
    "id": 4,
    "login": "github",
    "email": null,
    "organization_billing_email": "billing@github.com",
    "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/9",
        "accounts_url": "https://api.github.com/marketplace_listing/plans/9/accounts",
        "id": 9,
        "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,
        "bullets": [
          "This is the first bullet of the plan",
          "This is the second bullet of the plan"
        ]
      }
    }
  }
]

Check if a GitHub account is associated with any Marketplace listing

Note: The The GitHub Marketplace API on GitHub is currently available for developers to preview. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.valkyrie-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

GET /marketplace_listing/accounts/:id

Stubbed endpoint

GET /marketplace_listing/stubbed/accounts/:id

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "url": "https://api.github.com/orgs/github",
    "type": "Organization",
    "id": 4,
    "login": "github",
    "email": null,
    "organization_billing_email": "billing@github.com",
    "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/9",
        "accounts_url": "https://api.github.com/marketplace_listing/plans/9/accounts",
        "id": 9,
        "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,
        "bullets": [
          "This is the first bullet of the plan",
          "This is the second bullet of the plan"
        ]
      }
    }
  }
]

Response when the account has not purchased the listing

Status: 404 Not Found

Get a user's Marketplace purchases

Note: The The GitHub Marketplace API on GitHub is currently available for developers to preview. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.valkyrie-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

Returns only active subscriptions. You need to authenticate this call with the user's OAuth token.

GET /user/marketplace_purchases

Stubbed endpoint

GET /user/marketplace_purchases/stubbed

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "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,
      "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/9",
      "accounts_url": "https://api.github.com/marketplace_listing/plans/9/accounts",
      "id": 9,
      "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,
      "bullets": [
        "This is the first bullet of the plan",
        "This is the second bullet of the plan"
      ]
    }
  }
]