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:

Read the contents of the signing key from the credentials.
Use the signing key to generate a JSON Web Token (JWT).
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/owners"
```0

Example response:

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

#### Create a subscription

Use a POST command to create a subscription.

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

| 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 billable users in the current subscription term |
| `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:

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

Example response:

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

#### Update a subscription

Use a PUT command to update an existing subscription.

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

| 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 billable users in the current subscription term |
| `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:

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

Example response:

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

### Upcoming Reconciliations

The `upcoming_reconciliations` endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
to update upcoming reconciliations for namespaces.

#### Update an upcoming reconciliation

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

| 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:

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

Example response:

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

#### Delete an upcoming reconciliation

Use a DELETE command to delete an `upcoming_reconciliation`.

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

Example request:

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

Example response:

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

### Users

#### Retrieve a user

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

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

Example request:

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

Example response:

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

#### Fetch user permissions in a namespace

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

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

Example request:

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

Example response:

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

#### Update credit card validation

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

```plaintext
GET /internal/gitlab_subscriptions/namespaces/:id
```0

Example request:

```plaintext
GET /internal/gitlab_subscriptions/namespaces/:id
```1

Example response:

```plaintext
GET /internal/gitlab_subscriptions/namespaces/:id
```2

### Add-On Purchases

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

#### Create multiple subscription add-on purchases (Internal)

Use a POST command to create, update, and deprovision multiple subscription add-on purchases. Possible add-on types are `duo_pro`, `duo_enterprise`, and `product_analytics`.

```plaintext
GET /internal/gitlab_subscriptions/namespaces/:id
```3

Supported attributes:

| Attribute   | Type    | Required | Description |
|:------------|:--------|:---------|:------------|
| `quantity` | integer | No | Amount of units in the subscription add-on purchase. Must be a non-negative integer. (Example: Number of seats for Duo Pro 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 |

If successful, returns [`201`](../../api/rest/troubleshooting.md#status-codes) and the following response attributes:

| Attribute       | Type    | Description |
|:----------------|:--------|:------------|
| `namespace_id`  | integer | Unique identifier for the namespace associated with the purchase |
| `namespace_name`| string  | Name of the namespace linked to the purchase |
| `add_on`        | integer | Type of add-on related to the purchase. Possible add-on types are `Code Suggestions` alias Duo Pro, `Duo Enterprise` and `Product Analytics`  |
| `quantity`      | integer | Number of units purchased for the subscription add-on |
| `started_on`    | date    | Date the subscription add-on became active |
| `expires_on`    | date    | Date the subscription add-on will expire |
| `purchase_xid`  | string  | Unique identifier for the subscription add-on purchase |
| `trial`         | boolean | Indicates whether the add-on is part of a trial |

Example request for create/update:

```plaintext
GET /internal/gitlab_subscriptions/namespaces/:id
```4

Example request for deprovision:

```plaintext
GET /internal/gitlab_subscriptions/namespaces/:id
```5

The dates should reflect the day prior to the request, i.e., yesterday.

Example response:

```plaintext
GET /internal/gitlab_subscriptions/namespaces/:id
```6

#### Fetch a subscription add-on purchases

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

```plaintext
GET /internal/gitlab_subscriptions/namespaces/:id
```7

Example request:

```plaintext
GET /internal/gitlab_subscriptions/namespaces/:id
```8

Example response:

```plaintext
GET /internal/gitlab_subscriptions/namespaces/:id
```9

### Compute Minutes provisioning

The compute minutes endpoints are used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`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.

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

| 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:

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

Example response:

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

#### Move additional packs

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

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

| 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:

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

Example response:

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

## Deprecated Endpoints

These endpoints have been [migrated to internal endpoints](https://gitlab.com/gitlab-org/gitlab/-/issues/463741). Now, they are
deprecated and will be [removed in a future milestone](https://gitlab.com/gitlab-org/gitlab/-/issues/473625).

### Add-On Purchases (deprecated)

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

#### Create a subscription add-on purchase (deprecated)

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

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

| 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:

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

Example response:

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

#### Update a subscription add-on purchase (deprecated)

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

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

| 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:

```json
{
  "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
}
```0

Example response:

```json
{
  "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
}
```1

#### Fetch a subscription add-on purchases (deprecated)

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

```json
{
  "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
}
```2

Example request:

```json
{
  "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
}
```3

Example response:

```json
{
  "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
}
```4

### Compute quota provisioning (deprecated)

> - [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" and "compute minutes" in GitLab 16.1.

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

#### Create an additional pack (deprecated)

Use a POST command to create additional packs.

```json
{
  "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
}
```5

| 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:

```json
{
  "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
}
```6

Example response:

```json
{
  "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
}
```7

#### Move additional packs (deprecated)

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

```json
{
  "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
}
```8

| 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:

```json
{
  "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
}
```9

Example response:

```plaintext
PUT /internal/gitlab_subscriptions/namespaces/:id
```0

### Subscriptions (deprecated)

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

#### Create a subscription (deprecated)

Use a POST command to create a subscription.

```plaintext
PUT /internal/gitlab_subscriptions/namespaces/:id
```1

| 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:

```plaintext
PUT /internal/gitlab_subscriptions/namespaces/:id
```2

Example response:

```plaintext
PUT /internal/gitlab_subscriptions/namespaces/:id
```3

#### Update a subscription (deprecated)

Use a PUT command to update an existing subscription.

```plaintext
PUT /internal/gitlab_subscriptions/namespaces/:id
```4

| 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:

```plaintext
PUT /internal/gitlab_subscriptions/namespaces/:id
```5

Example response:

```plaintext
PUT /internal/gitlab_subscriptions/namespaces/:id
```6

#### Fetch a subscription (deprecated)

Use a GET command to view an existing subscription.

```plaintext
PUT /internal/gitlab_subscriptions/namespaces/:id
```7

Example request:

```plaintext
PUT /internal/gitlab_subscriptions/namespaces/:id
```8

Example response:

```plaintext
PUT /internal/gitlab_subscriptions/namespaces/:id
```9