GitLab Subscriptions Internal API

The GitLab Subscriptions internal API is used by the CustomersDot application, it cannot be used by other consumers. This documentation is intended for people working on the GitLab and CustomersDot codebases.

Add new endpoints

API endpoints should be externally accessible by default, with proper authentication and authorization. Before adding a new internal endpoint, consider if the API would benefit the wider GitLab community and can be made externally accessible.

For the GitLab Subscription portal, we might chose to use an internal API when we need to make updates to GitLab without the context of a user. This means we don’t have access to a user’s access token, and instead make updates as the CustomersDot application in general.

Authentication

CustomersDot JWT

These endpoints are all authenticated using JWT authentication from CustomersDot.

To authenticate using the JWT, clients:

  1. Read the contents of the signing key from the credentials.
  2. Use the signing key to generate a JSON Web Token (JWT).
  3. Pass the JWT in the X-CUSTOMERS-DOT-INTERNAL-TOKEN header.

Admin personal access token (PAT)

This authentication method is deprecated as it is not supported in the Cells architecture. It will be removed in a future milestone. Please use JWT authentication instead.

To authenticate as an administrator, generate a personal access token for an administrator with the api and admin_mode scopes. This token can then be supplied in the PRIVATE-TOKEN header.

Internal Endpoints

Namespaces

Fetch group owners

Use a GET command to get direct owners of the namespace. CustomersDot uses this endpoint to find users to notify about billing events. 

GET /internal/gitlab_subscriptions/namespaces/:id/owners

Example request: 

curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1234/owners"

Example response: 

[
  {
    "user": {
      "id": 1,
      "username": "john_smith",
      "name": "John Smith"
    },
    "access_level": 50,
    "notification_email": "name@example.com"
  }
]

Fetch a namespace by ID

Used to fetch information about a namespace. 

GET /internal/gitlab_subscriptions/namespaces/:id

Parameters:

Attribute Type Required Description
id integer/string yes ID or URL-encoded path of the namespace

Example request: 

curl --request GET --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1"

Example response: 

{
  "id": 1,
  "name": "group1",
  "path": "group1",
  "kind": "group",
  "full_path": "group1",
  "parent_id": null,
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/group1",
  "members_count_with_descendants": 2,
  "billable_members_count": 2,
  "max_seats_used": 0,
  "seats_in_use": 0,
  "plan": "default",
  "end_date": null,
  "trial_ends_on": null,
  "trial": false,
  "root_repository_size": 100,
  "projects_count": 3
}

Update a namespace

Use a PUT command to update an existing namespace. 

PUT /internal/gitlab_subscriptions/namespaces/:id

Parameters:

Attribute Type Required Description
id integer/string yes ID or URL-encoded path of the namespace
shared_runners_minutes_limit integer no Compute minutes quota
extra_shared_runners_minutes_limit integer no Extra compute minutes
additional_purchased_storage_size integer no Additional storage size
additional_purchased_storage_ends_on date no Additional purchased storage Ends on
gitlab_subscription_attributes hash no Hash object containing GitLab Subscription attributes. Accepts seats,max_seats_used,plan_code,end_date,auto_renew,trial,trial_ends_on,trial_starts_on,trial_extension_type

Example request: 

curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1 --data '{"shared_runners_minutes_limit":1000}'"

Example response: 

{
  "id": 1,
  "name": "group1",
  "path": "group1",
  "kind": "group",
  "full_path": "group1",
  "parent_id": null,
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/group1",
  "members_count_with_descendants": 2,
  "billable_members_count": 2,
  "max_seats_used": 0,
  "seats_in_use": 0,
  "plan": "default",
  "end_date": null,
  "trial_ends_on": null,
  "trial": false,
  "root_repository_size": 100,
  "projects_count": 3
}

Subscriptions

The subscription endpoints are used by CustomersDot (customers.gitlab.com) to apply subscriptions (including trials, and add-on purchases) to personal namespaces, or top-level groups on GitLab.com.

Fetch a subscription

Use a GET command to view an existing subscription. 

GET /internal/gitlab_subscriptions/namespaces/:id/gitlab_subscription

Example request: 

curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1234/gitlab_subscription"

Example response: 

{
  "plan": {
    "code": "premium",
    "name": "premium",
    "trial": false,
    "auto_renew": null,
    "upgradable": false,
    "exclude_guests": false
  },
  "usage": {
    "seats_in_subscription": 80,
    "seats_in_use": 82,
    "max_seats_used": 82,
    "seats_owed": 2
  },
  "billing": {
    "subscription_start_date": "2020-07-15",
    "subscription_end_date": "2021-07-15",
    "trial_ends_on": null
  }
}

Upcoming Reconciliations

The upcoming_reconciliations endpoint is used by CustomersDot (customers.gitlab.com) to update upcoming reconciliations for namespaces.

Update an upcoming reconciliation 

PUT /internal/gitlab_subscriptions/namespaces/:namespace_id/upcoming_reconciliations
Attribute Type Required Description
namespace_id ID yes ID of the namespace with the upcoming reconciliation
next_reconciliation_date date yes Date the reconciliation will occur on
display_alert_from date yes Date to start display the upcoming reconciliation alert

Example request: 

curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" --header "Content-Type: application/json" \
     --data '{"upcoming_reconciliations": [{"next_reconciliation_date": "12 Jun 2021", "display_alert_from": "05 Jun 2021"}]}' \
     "https://gitlab.com/api/v4/internal/gitlab_subscriptions/129/upcoming_reconciliations"

Example response: 

200

Delete an upcoming reconciliation

Use a DELETE command to delete an upcoming_reconciliation. 

DELETE /internal/gitlab_subscriptions/namespaces/:namespace_id/upcoming_reconciliations

Example request: 

curl --request DELETE \
  --url "http://localhost:3000/api/v4/internal/gitlab_subscriptions/namespaces/22/upcoming_reconciliations" \
  --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>"

Example response: 

204

Users

Retrieve a user

Use a GET command to get the User object based on user ID. 

GET /internal/gitlab_subscriptions/users/:id

Example request: 

curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/users/:id"

Example response: 

{
  "id": 1,
  "username": "john_smith",
  "name": "John Smith",
  "web_url": "http://localhost:3000/john_smith"
}

Fetch user permissions in a namespace

Use a GET command to fetch the permissions a user has in a namespace. 

GET /internal/gitlab_subscriptions/namespaces/:namespace_id/user_permissions/:user_id

Example request: 

curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/:namespace_id/user_permissions/:user_id"

Example response: 

{
  "edit_billing": true
}

Update credit card validation

Use a PUT command to update the User’s credit card validation 

PUT /internal/gitlab_subscriptions/users/:user_id/credit_card_validation

Example request: 

curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" \
     --data '{"credit_card_validated_at": "2020-01-01 00:00:00 UTC", "credit_card_expiration_year": "2010", "credit_card_expiration_month": "12", "credit_card_holder_name": "John Smith", "credit_card_type": "American Express", "credit_card_mask_number": "1111", "zuora_payment_method_xid": "abc123", "stripe_setup_intent_xid": "seti_abc123", "stripe_payment_method_xid": "pm_abc123", "stripe_card_fingerprint": "card123"}' \
     "https://gitlab.com/api/v4/internal/gitlab_subscriptions/users/:user_id/credit_card_validation"

Example response: 

{
  "success": {}
}

Migrating Endpoints

These endpoints are going to be migrated to internal endpoints. After that, they will be deprecated and then removed in a future milestone.

Add-On Purchases

This API is used by CustomersDot to manage add-on purchases, excluding Compute Minutes and Storage packs.

Create a subscription add-on purchase

Use a POST command to create a subscription add-on purchase. 

POST /namespaces/:id/subscription_add_on_purchase/:add_on_name
Attribute Type Required Description
quantity integer yes Amount of units in the subscription add-on purchase (Example: Number of seats for a Code Suggestions add-on)
started_on date yes Date the subscription add-on purchase became available
expires_on date yes Expiration date of the subscription add-on purchase
purchase_xid string yes Identifier for the subscription add-on purchase (Example: Subscription name for a Code Suggestions add-on)
trial boolean no Whether the add-on is a trial

Example request: 

curl --request POST --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=10&started_on="2024-06-15"&expires_on="2024-07-15"&purchase_xid="A-S12345678"&trial=true"

Example response: 

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":10,
  "started_on":"2024-06-15",
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678",
  "trial":true
}

Update a subscription add-on purchase

Use a PUT command to update an existing subscription add-on purchase. 

PUT /namespaces/:id/subscription_add_on_purchase/:add_on_name
Attribute Type Required Description
quantity integer no Amount of units in the subscription add-on purchase (Example: Number of seats for a Code Suggestions add-on)
started_on date yes Date the subscription add-on purchase became available
expires_on date yes Expiration date of the subscription add-on purchase
purchase_xid string no Identifier for the subscription add-on purchase (Example: Subscription name for a Code Suggestions add-on)
trial boolean no Whether the add-on is a trial

Example request: 

curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=15&started_on="2024-06-15"&expires_on="2024-07-15"&purchase_xid="A-S12345678"&trial=true"

Example response: 

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":15,
  "started_on":"2024-06-15",
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678",
  "trial":true
}

Fetch a subscription add-on purchases

Use a GET command to view an existing subscription add-on purchase. 

GET /namespaces/:id/subscription_add_on_purchase/:add_on_name

Example request: 

curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions"

Example response: 

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":15,
  "started_on":"2024-06-15",
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678",
  "trial":true
}

Compute quota provisioning

History
  • Renamed from “CI/CD minutes” to “compute quota” and “compute minutes” in GitLab 16.1.

The compute quota endpoints are used by CustomersDot (customers.gitlab.com) to apply additional packs of compute minutes, for personal namespaces or top-level groups in GitLab.com.

Create an additional pack

Use a POST command to create additional packs. 

POST /namespaces/:id/minutes
Attribute Type Required Description
packs array yes An array of purchased compute packs
packs[expires_at] date yes Expiry date of the purchased pack
packs[number_of_minutes] integer yes Number of additional compute minutes
packs[purchase_xid] string yes The unique ID of the purchase

Example request: 

curl --request POST \
  --url "http://localhost:3000/api/v4/namespaces/123/minutes" \
  --header 'Content-Type: application/json' \
  --header 'X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>' \
  --data '{
    "packs": [
      {
        "number_of_minutes": 10000,
        "expires_at": "2022-01-01",
        "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
      }
    ]
  }'

Example response: 

[
  {
    "namespace_id": 123,
    "expires_at": "2022-01-01",
    "number_of_minutes": 10000,
    "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
  }
]

Move additional packs

Use a PATCH command to move additional packs from one namespace to another. 

PATCH /namespaces/:id/minutes/move/:target_id
Attribute Type Required Description
id string yes The ID of the namespace to transfer packs from
target_id string yes The ID of the target namespace to transfer the packs to

Example request: 

curl --request PATCH \
  --url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \
  --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>"

Example response: 

{
  "message": "202 Accepted"
}

Subscriptions (being migrated)

The subscription endpoints are used by CustomersDot (customers.gitlab.com) to apply subscriptions (including trials) to personal namespaces, or top-level groups on GitLab.com.

Create a subscription

Use a POST command to create a subscription. 

POST /namespaces/:id/gitlab_subscription
Attribute Type Required Description
start_date date yes Start date of subscription
end_date date no End date of subscription
plan_code string no Subscription tier code
seats integer no Number of seats in subscription
max_seats_used integer no Highest number of active users in the last month
auto_renew boolean no Whether subscription auto-renews on end date
trial boolean no Whether subscription is a trial
trial_starts_on date no Start date of trial
trial_ends_on date no End date of trial

Example request: 

curl --request POST --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="premium"&seats=10"

Example response: 

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false
  },
  "usage": {
    "seats_in_subscription":10,
    "seats_in_use":1,
    "max_seats_used":0,
    "seats_owed":0
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":null,
    "trial_ends_on":null
  }
}

Update a subscription

Use a PUT command to update an existing subscription. 

PUT /namespaces/:id/gitlab_subscription
Attribute Type Required Description
start_date date no Start date of subscription
end_date date no End date of subscription
plan_code string no Subscription tier code
seats integer no Number of seats in subscription
max_seats_used integer no Highest number of active users in the last month
auto_renew boolean no Whether subscription auto-renews on end date
trial boolean no Whether subscription is a trial
trial_starts_on date no Start date of trial. Required if trial is true.
trial_ends_on date no End date of trial

Example request: 

curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0"

Example response: 

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false
  },
  "usage": {
    "seats_in_subscription":80,
    "seats_in_use":82,
    "max_seats_used":0,
    "seats_owed":2
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":"2021-07-15",
    "trial_ends_on":null
  }
}

Deprecated Endpoints

These endpoints are no longer being used by CustomersDot as an internal version of these endpoints has already been created. They will be removed in a future milestone.

Subscriptions (deprecated)

These endpoints have been replaced with the ones in the Internal Subscriptions API.

Fetch a subscription (namespaces API)

Use a GET command to view an existing subscription. 

GET /namespaces/:id/gitlab_subscription

Example request: 

curl --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription"

Example response: 

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
    "exclude_guests":false
  },
  "usage": {
    "seats_in_subscription":80,
    "seats_in_use":82,
    "max_seats_used":82,
    "seats_owed":2
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":"2021-07-15",
    "trial_ends_on":null
  }
}