Marketplace partners

GitLab supports automation for selected distribution marketplaces to process sales of GitLab products to authorized channel partners. Marketplace partners can use the GitLab Marketplace APIs to integrate their systems with GitLab to sell GitLab subscriptions on their site.

This document’s target audience is third-party developers for Marketplace partners.

How the Marketplace APIs work

The Marketplace APIs are hosted in the Customers Portal. The Customers Portal allows individual customers to purchase and manage GitLab subscriptions and supports APIs for partners to make sales on behalf of their customers. The Customers Portal integrates with other GitLab services, including Zuora and Salesforce, to provide a task-oriented interface for users.

The following example shows a typical purchase flow of request and response between the following components:

  • Customer
  • Marketplace partner system
  • Customers Portal
  • Zuora
  • Salesforce
sequenceDiagram participant Customer participant Marketplace partner system participant Customers Portal participant Zuora participant Salesforce Customer ->> Marketplace partner system: Place order to purchase GitLab subscription Marketplace partner system ->> Customers Portal: Get OAuth token Customers Portal ->> Marketplace partner system: Access token Marketplace partner system ->> Customers Portal: Place order Customers Portal ->> Zuora: Create Zuora subscription Customers Portal ->> Salesforce: Create Salesforce objects Zuora ->> Customers Portal: Success response with Zuora subscription data Customers Portal ->> Marketplace partner system: Success response with order ID Zuora ->> Customers Portal: Zuora callout event Customers Portal ->> Customer: send license notification Marketplace partner system ->> Customers Portal: Poll order status Customers Portal ->> Marketplace partner system: Success response with order status

Marketplace API Specification

OpenAPI specs for the Marketplace APIs are available at Marketplace interactive API documentation.

Access the Marketplace API

To access the Marketplace API you need to:

  • Request access from GitLab.
  • Retrieve an OAuth access token.

Marketplace API endpoints are secured with OAuth 2.0. OAuth is an authorization framework that grants 3rd party or client applications, like a Marketplace partner application, limited access to resources on an HTTP service, like the Customers Portal.

OAuth 2.0 uses grant types (or flows) that describe how a client application gets authorization in the form of an access token. An access token is a string that the client application uses to make authorized requests to the resource server.

The Marketplace API uses the client_credentials grant type. The client application uses the access token to access its own resources, instead of accessing resources on behalf of a user.

Step 1: Request access

Before you can use the Marketplace API, you must contact your Marketplace partner Manager or email partnerorderops to request access. After you request access, GitLab configures the following accounts and credentials for you:

  1. Client credentials. Marketplace APIs are secured with OAuth 2.0. The client credentials include the client ID and client secret that you need to retrieve the OAuth access token.
  2. Invoice owner account in Zuora system. Required for invoice processing.
  3. Distributor account in Salesforce system.
  4. Trading partner account in Salesforce system. GitLab adds the Trading Partner ID to a permitted list to pass the validations.

Step 2: Retrieve an access token

To retrieve an access token,

  • Make a POST request to the /oauth/token endpoint with the following required parameters:
Parameter Type Required Description
client_id string yes ID of your client application record on the Customers Portal. Received from GitLab.
client_secret string yes Secret of your client application record on the Customers Portal. Received from GitLab.
grant_type string yes Specifies the type of credential flow. Use client_credentials.
scope string yes Specifies the level of access. Use marketplace.order:read for read-only access. Use marketplace.order:create for create access.

If the request is successful, the response body includes the access token that you can use in subsequent requests. For an example of a successful response, see the Marketplace interactive API documentation

If the request is unsuccessful, the response body includes an error and error description. The errors can be:

Status Description
400 Invalid scope. Ensure the scope is marketplace.order:read or marketplace.order:create.
401 Invalid client. Ensure that there are no typos or extra spaces on the client specific credentials. Incorrect client_id or client_secret

Step 3: Use the access token

To use the access token from a client application:

  1. Set the Authorization header of the request to Bearer <your_access_token>.
  2. Set parameters or data needed for the endpoint and send the request.

Example request: 

curl \
  --url "https://customers.staging.gitlab.com/api/v1/marketplace/subscriptions/:external_subscription_id" \
  --header "Authorization: Bearer NHb_VhZhPOnBTSNfBSzmCmt28lLDWb2xtwr_c3DL148"

Create a new customer subscription

To create a new customer subscription from a Marketplace partner client application,

Parameter Type Required Description
externalSubscriptionId string yes ID of the subscription on the Marketplace partner system.
tradingPartnerId string yes ID of the Trading Partner account in Salesforce. Received from GitLab.
customer object yes Information about the customer. Must include company name. Contact must include firstName, lastName and email. Address must include country.
orderLines array yes Specifies the product purchased. Must include quantity and productId.

If the request is successful, the response body includes the newly created subscription number. For an example of a full request body, see the Marketplace interactive API documentation.

If the subscription creation is unsuccessful, the response body includes an error message with details about the cause of the error.

Check the status of a subscription

To get the status of a given subscription,

The request must include the Marketplace partner system ID of the subscription to fetch the status for.

If the request is successful, the response body contains the status of the subscription provision. The status can be:

  • Creating
  • Created
  • Failed
  • Provisioned

If the subscription cannot be found using the passed external_subscription_id, the response has a 404 Not Found status.