What is GitHub Marketplace?
GitHub Marketplace is an online platform that allows developers and organizations to discover, purchase, and manage tools that integrate directly with the GitHub ecosystem. These tools range from continuous integration and deployment services to security automation, code quality assessment, and project management apps.
By offering a central location for vetted third-party apps, the Marketplace simplifies software development workflows, making it easier for teams to add functionality without leaving GitHub’s interface. The Marketplace benefits both developers looking for new solutions and vendors seeking to distribute their tools.
Developers gain access to a variety of integrations with transparent pricing, support for free and paid offerings, and the ability to manage subscriptions directly through their GitHub accounts. Vendors can reach a large audience of GitHub users, use GitHub’s billing infrastructure, and provide easy installation and configuration experiences.
This is part of a series of articles about GitHub actions
Pricing plans for GitHub Marketplace apps
GitHub Marketplace apps can offer up to ten different pricing plans to accommodate various user needs. These plans fall into three main categories: free, flat rate, and per-unit. All prices must be listed in U.S. dollars and apply on both monthly and annual terms. Only verified publishers can offer paid plans.
-
Free plans allow developers to provide access to their apps at no cost and are commonly used to support open source projects. However, if the same app is available as a paid product outside the Marketplace, a paid plan must also be offered within GitHub once it meets eligibility criteria.
-
Flat rate pricing charges users a fixed fee per month or year, regardless of usage.
-
Per-unit pricing scales based on the number of users in an organization, with fees applied per user. Both paid plan types can optionally include a 14-day free trial. During the trial period, customers are notified before auto-enrollment occurs unless the trial is canceled.
Billing and subscription management are handled through GitHub’s platform, so developers don’t need to implement their own payment systems. However, all apps must respond to events from the GitHub Marketplace API to manage purchases, cancellations, and plan changes.
Setting pricing plans for your GitHub Marketplace listing
When creating a pricing plan for a GitHub Marketplace listing, publishers can choose between offering their app for free or selling it through one or more paid tiers. Paid listings require the app to be owned by a verified organization that has completed GitHub’s publisher verification process.
Pricing plans can be drafted or published. Draft plans allow publishers to configure and save plans without making them publicly visible. Once published, plans on approved listings become immediately available for purchase. Each listing can include up to ten pricing plans, covering free, flat-rate, and per-unit models. All paid plans must include pricing in U.S. dollars for both monthly and yearly subscriptions and must support GitHub’s Marketplace API for handling purchases, cancellations, and plan changes.
To create a plan, publishers navigate to the “Plans and pricing” section in their app listing and start a new draft. Required fields include a plan name, pricing model, availability (personal accounts, organizations, or both), a short description, and up to four bullet points highlighting features or use cases. Publishers may also choose to enable a 14-day free trial, which automatically converts to a paid subscription unless canceled by the user.
If pricing changes are needed after a plan is published, the existing plan must be removed and a new one created. Customers on a retired plan will remain on it until they cancel or switch plans. Free trials can be switched off without removing the plan.
Understanding the billing cycle in GitHub Marketplace
GitHub Marketplace supports both monthly and yearly billing cycles, and customers choose one during purchase. Each time a customer changes their billing cycle or switches plans, GitHub sends a marketplace_purchase webhook event. This webhook includes details like the effective_date, which indicates when the new billing cycle or plan will begin.
Apps listed on the Marketplace must use this webhook data to track changes in billing status. Developers can refer to the GitHub Marketplace API documentation to implement event handling for plan changes, cancellations, and new purchases.
Apps must also provide billing visibility and control through their own user interface. This includes allowing users to upgrade or cancel plans, manage user access if using per-unit pricing, and view updates on current plans, usage, pricing, and trial status. For example, per-unit plans should clearly show how many seats are used and how many are still available.
Cancellations When customers cancel a paid plan, they must be automatically downgraded to a free tier, if one is available. GitHub does not uninstall the app upon cancellation, so free features should remain active. Additionally, users should have the option to re-enable their previous paid plan later if they choose.
Upgrades Upgrades must take effect immediately, and apps are required to apply a prorated discount when changing from monthly to yearly billing or to a higher-priced tier. If an upgrade fails due to payment issues, GitHub reverts the subscription to the prior plan and notifies the customer via email. Developers will also receive a webhook event prompting them to roll back the plan change.
For downgrades and cancellations, no refunds are required. The current plan continues until the end of the billing period, and the new plan takes effect at the start of the next cycle, as indicated by the webhook event.
Tutorial: Handling pricing plan changes through GitHub Marketplace API
To manage pricing plan changes for your GitHub Marketplace app, you must handle marketplace_purchase webhook events with the changed action. These events occur when a customer upgrades or downgrades their plan, changes their billing cycle, or modifies the number of seats in a per-unit pricing model.
Handle the webhook event
When a plan change occurs, GitHub sends a marketplace_purchase webhook with the changed action. The webhook includes fields like effective_date, marketplace_purchase, and previous_marketplace_purchase, which indicate when the new plan should take effect and provide details about the customer’s old and new subscriptions.
- Upgrades (e.g., moving to a higher-priced plan or switching from monthly to annual billing) trigger immediate webhook delivery so customers gain access to premium features right away.
- Downgrades take effect at the end of the current billing cycle, and the webhook is sent at that time.
- Free trial expirations also trigger a
changedwebhook, requiring the app to convert the user to a paid tier automatically.
Update customer account details
After receiving the webhook, update the customer’s subscription status in your app. Adjust billing cycle data, pricing plan information, and seat counts (if applicable). For downgrade events, verify if the customer exceeds usage limits of the new plan, and consider notifying them in-app or via email.
Your app should also show current subscription details—such as plan type, billing term, and seat usage—within its UI. This gives customers transparency and helps them manage their subscriptions more effectively.
Handling failed upgrade payments
If an upgrade fails due to payment issues, GitHub rolls the customer’s subscription back to the previous plan and notifies them via email. Your app will receive another marketplace_purchase webhook indicating the reversion. In response, you must restore the user’s access to the prior plan and its features.
Using upgrade URLs
To encourage plan upgrades, you can integrate upgrade links directly into your app. These links take users to the upgrade confirmation page on GitHub. The URL format is:
https://www.github.com/marketplace/<LISTING_NAME>/upgrade/<LISTING_PLAN_NUMBER>/<CUSTOMER_ACCOUNT_ID>
You can retrieve LISTING_PLAN_NUMBER and LISTING_PLAN_ID when you list your available pricing plans. The CUSTOMER_ACCOUNT_ID is accessible via the GET /marketplace_listing/plans/{plan_id}/accounts endpoint.
Use upgrade URLs in banners, buttons, or notifications within your UI to simplify the upgrade process for customers.
Periodic synchronization
To ensure your records are up-to-date, perform periodic checks using the GitHub API. Call GET /marketplace_listing/plans/:id/accounts to validate that plan IDs, billing cycles, and seat counts match the data on GitHub’s side. This helps prevent billing discrepancies and ensures consistent subscription handling.
Related content: Read our guide to GitHub Actions deployments
Conclusion
GitHub Marketplace streamlines the distribution and management of developer tools by integrating billing, subscription handling, and plan customization directly into GitHub’s platform. By supporting multiple pricing models, webhook-based event tracking, and in-app upgrade capabilities, it gives publishers robust tools for monetization while offering users transparency and ease of use.
Help us continuously improve
Please let us know if you have any feedback about this page.
