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 "About 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

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

GET /marketplace_listing/plans/:id/accounts

Stubbed endpoint

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

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",
      "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

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",
      "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"
        ]
      }
    }
  }
]

Get a user's Marketplace purchases

GET /user/marketplace_purchases

Note: This call must be authenticated with a user's OAuth token.

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",
    "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"
      ]
    }
  }
]