Cette page a été traduite par l'API Cloud Translation.

Récupérer et mettre à jour un abonnement

Une fois que vous avez récupéré un abonnement, vous pouvez utiliser les informations de la réponse réussie pour modifier l'état de l'abonnement ou le mettre à jour. Cette page présente les différentes façons de récupérer et de mettre à jour un abonnement.

Récupérer un abonnement

Pour récupérer un abonnement commandé ou transféré avec succès, utilisez la requête HTTP GET suivante.

GET https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID

Remplacez les éléments suivants :

CUSTOMER_ID: nom de domaine principal du client ou identifiant unique du client.
SUBSCRIPTION_ID: identifiant de l'abonnement, qui est unique pour chaque client. Vous pouvez récupérer cette valeur à l'aide de la méthode Retrieve all reseller subscriptions (Récupérer tous les abonnements du revendeur).

Cette opération ne comporte aucun paramètre dans le corps de la requête.

Une réponse réussie renvoie un code d'état HTTP 200 et les paramètres de l'abonnement. Dans l'exemple de réponse suivant, la propriété isInTrial est false, mais il n'y a pas de propriété trialEndTime, ce qui signifie que ce client n'a jamais bénéficié d'un essai sans frais de 30 jours avec ce forfait.

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "billingMethod": "ONLINE",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "RENEW_CURRENT_USERS_MONTHLY_PAY"
  },
  "purchaseOrderId": "example.com_annual_1",
  "status": "ACTIVE",
  "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
  "skuName": "Google Workspace Business Standard"
}

Récupérer tous les abonnements d'un client

Pour récupérer tous les abonnements d'un client revendeur spécifique qui ont été commandés ou transférés, utilisez la requête HTTP GET suivante et incluez le jeton d'autorisation:

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID value&pageToken=START_DATE&maxResults=MAX_NUMBER

Remplacez les éléments suivants :

CUSTOMER_ID: nom de domaine principal du client ou identifiant unique du client.
START_DATE: date de début au format YYYY-MM-DD.
MAX_NUMBER: nombre maximal de résultats renvoyés sur une page de réponse.

Cette opération ne comporte aucun paramètre dans le corps de la requête.

Une réponse réussie renvoie un code d'état HTTP 200 et une liste des abonnements et des paramètres du client. La liste des abonnements peut inclure des produits qui ne sont pas gérés dans cette version de l'API Reseller.

Si vous ne gérez pas ce client, une erreur 403 "Forbidden" est renvoyée.

Récupérer tous les abonnements transférables d'un client

Pour récupérer tous les abonnements d'un client pouvant être transférés à la gestion du revendeur, utilisez la requête HTTP GET suivante et incluez le jeton d'autorisation. customerId est obligatoire et correspond à l'identifiant unique du client renvoyé lors de la récupération du compte d'un client revendu. customerAuthToken est un jeton de transfert fourni par votre client et spécifique à votre ID de revendeur. Une fois généré par le client, il est valable pendant 30 jours. Pour en savoir plus sur la façon dont les clients génèrent le jeton, consultez Transférer votre compte Google Workspace à un revendeur.

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID&customerAuthToken=AUTH_TOKEN&pageToken=START_DATE&maxResults=MAX_NUMBER

Remplacez les éléments suivants :

CUSTOMER_ID: nom de domaine principal du client ou identifiant unique du client.
AUTH_TOKEN: jeton de transfert fourni par votre client, spécifique à votre ID de revendeur. Une fois généré par le client, il est valable pendant 30 jours. Pour en savoir plus sur la façon dont les clients génèrent le jeton, consultez Transférer votre compte Google Workspace à un revendeur. Si cette valeur n'est pas valide ou a expiré, la réponse de l'API renvoie une erreur 403 "Forbidden".
START_DATE: date de début au format YYYY-MM-DD.
MAX_NUMBER: nombre maximal de résultats renvoyés sur une page de réponse.

Cette opération ne comporte aucun paramètre dans le corps de la requête.

Une réponse réussie renvoie un code d'état HTTP 200 et une liste des abonnements transférables du client, avec la date d'expiration du jeton de transfert et le nombre minimal de sièges requis dans la commande de transfert. Un client peut détenir des abonnements supplémentaires qui ne sont pas transférables.

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "432",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1331647980142",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "maximumNumberOfSeats": 500,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183980142",
        "minimumTransferableSeats": "20"
      },
      "purchaseOrderId": "PO_890",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "140",
      "skuId": "1010020028",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183780159",
        "minimumTransferableSeats": "10"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Si vous prévoyez de transférer ces abonnements à l'aide de l'opération par lot, transférez tous les abonnements. Le transfert de chaque abonnement individuellement génère une erreur. En outre, l'opération par lot ne transfère que les abonnements dont l'état est ACTIVE. Pour en savoir plus, consultez la section Transférer un abonnement.

Récupérer tous les abonnements de revendeur

Pour récupérer tous les abonnements commandés ou transférés avec succès par un revendeur, utilisez la requête HTTP GET suivante et incluez le jeton d'autorisation.

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=PREFIX &pageToken=TOKEN&maxResults=MAX_NUMBER

Remplacez les éléments suivants :

PREFIX: début du nom du client dont vous recherchez les abonnements.
TOKEN: jeton identifiant une page de résultats spécifique que le serveur doit renvoyer.
MAX_NUMBER: nombre maximal de résultats renvoyés sur une page de réponse.

Cette opération peut utiliser le niveau d'accès en lecture seule OAuth. customerNamePrefix, pageToken et maxResults sont des chaînes de requête facultatives.

L'exemple suivant récupère tous les abonnements d'un revendeur appartenant à des clients dont le nom commence par "exam":

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=exam

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "C0123456",
      "subscriptionId": "123",
      "skuId": "1010020028",
      "creationTime": "1331647980142",
      "billingMethod": "ONLINE",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "purchaseOrderId": "PO_135",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-5678",
      "subscriptionId": "1404686",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "AUTO_RENEW"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Modifier un forfait

La procédure de mise à jour des forfaits Google Workspace varie selon le forfait. Avant de mettre à jour un plan, tenez compte des points suivants:

Lorsque vous créez un abonnement et que le client remplit les conditions requises, le forfait de l'abonnement peut être un essai de 30 jours. Les forfaits modulables et les forfaits avec engagement annuel peuvent être assortis d'un essai sans frais de 30 jours. Pendant la période d'essai, vous pouvez modifier le forfait de l'abonnement en passant à un forfait modulable ou à un forfait annuel aussi souvent que nécessaire. Toutefois, une fois l'essai terminé et le forfait activé, la modification du forfait suit les mêmes règles que celles des autres forfaits actifs. Pour transférer immédiatement un abonnement d'essai vers un forfait actif, lancez un service payant à partir d'un abonnement d'essai sans frais de 30 jours. Pour en savoir plus sur l'essai de 30 jours et les règles d'éligibilité des clients, consultez le Centre d'aide pour les administrateurs.
Vous pouvez passer d'un forfait modulable à un forfait d'engagement annuel.
Vous ne pouvez pas modifier un forfait d'engagement annuel.
Les forfaits ne sont pas tous compatibles avec tous les produits. Pour en savoir plus sur les produits utilisés par ces forfaits, consultez la section Produits et codes SKU.

Pour modifier un forfait d'essai de 30 jours ou un abonnement flexible en forfait avec engagement annuel, utilisez la requête HTTP POST suivante:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changePlan

Remplacez les éléments suivants :

CUSTOMER_ID: nom de domaine principal du client ou identifiant unique du client.
SUBSCRIPTION_ID: identifiant de l'abonnement, qui est unique pour chaque client. Vous pouvez récupérer cette valeur à l'aide de la méthode Retrieve all reseller subscriptions (Récupérer tous les abonnements du revendeur).

L'exemple suivant met à jour l'abonnement avec subscriptionId avec une valeur de 123. customerId est défini sur C0123456.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changePlan

Le corps de la requête comprend les éléments suivants:

{
  "kind": "reseller#changePlanRequest",
  "planName": "ANNUAL_MONTHLY_PAY",
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10
  },
  "purchaseOrderId": "123_March2012"
}

Une réponse réussie renvoie un code d'état HTTP 201 et les paramètres du forfait d'abonnement mis à jour:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "purchaseOrderId": "123_March2012",
  "status": "ACTIVE",
  "skuName": "Google Workspace Business Standard"
}

Modifier les licences utilisateur d'un abonnement

La modification d'un abonnement avec engagement annuel utilise des propriétés d'abonnement différentes de celles de la modification d'un abonnement avec forfait modulable Google Workspace.

Modifier le nombre de licences pour un abonnement avec forfait annuel

Pour mettre à jour les paramètres de licence utilisateur d'un abonnement à un forfait annuel, utilisez la requête HTTP POST suivante:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeSeats

Remplacez les éléments suivants :

CUSTOMER_ID: nom de domaine principal du client ou identifiant unique du client.
SUBSCRIPTION_ID: identifiant de l'abonnement, qui est unique pour chaque client. Vous pouvez récupérer cette valeur à l'aide de la méthode Retrieve all reseller subscriptions (Récupérer tous les abonnements du revendeur).

L'exemple suivant met à jour l'abonnement avec l'subscriptionId 123. customerId est défini sur C0123456. Le corps de la requête diffère selon le type de forfait:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changeSeats

L'abonnement d'un forfait Google Workspace avec engagement annuel utilise ce corps de requête pour mettre à jour le nombre de licences utilisateur. La valeur numberOfSeats est un total. Par exemple, si vous disposiez auparavant de 10 licences utilisateur et que vous avez une commande client pour cinq nouvelles licences, le total dans le corps de la requête pour numberOfSeats est de 15, comme illustré dans l'exemple suivant:

{
    "kind": "subscriptions#seats",
    "numberOfSeats": 15
}

Mettre à jour les licences utilisateur d'un abonnement avec forfait modulable

L'abonnement d'un forfait modulable Google Workspace utilise le corps de la requête pour mettre à jour les licences utilisateur. La valeur maximumNumberOfSeats correspond au total des licences existantes et des nouvelles licences. Il s'agit du nombre maximal de licences utilisateur que le compte peut provisionner.

{
  "kind": "subscriptions#seats",
  "maximumNumberOfSeats": 15
}

Une réponse réussie renvoie un code d'état HTTP 201 et les paramètres de licence d'abonnement mis à jour:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "FLEXIBLE",
    "isCommitmentPlan": false
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 15,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "skuName": "Google Workspace Business Standard"
}

Modifier les paramètres de renouvellement d'un abonnement

Pour mettre à jour les paramètres de renouvellement d'un abonnement avec engagement annuel, utilisez la requête HTTP POST suivante:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeRenewalSettings

Remplacez les éléments suivants :

CUSTOMER_ID: nom de domaine principal du client ou identifiant unique du client.
SUBSCRIPTION_ID: identifiant de l'abonnement, qui est unique pour chaque client. Vous pouvez récupérer cette valeur à l'aide de la méthode Retrieve all reseller subscriptions (Récupérer tous les abonnements du revendeur).

Voici un exemple de corps de requête:

{
  "kind": "subscriptions#renewalSettings",
  "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
}

La valeur de la propriété renewalType peut être l'une des suivantes:

AUTO_RENEW_YEARLY_PAY: à la fin de la période d'un forfait d'engagement annuel, le forfait de l'abonnement est automatiquement renouvelé en tant que ANNUAL_YEARLY_PAY avec le même numberOfSeats.
AUTO_RENEW_MONTHLY_PAY: à la fin de la période d'un forfait d'engagement annuel, le forfait de l'abonnement est automatiquement renouvelé en tant que ANNUAL_MONTHLY_PAY avec le même numberOfSeats.
RENEW_CURRENT_USERS_YEARLY_PAY: à la fin de la période d'engagement annuel, renouvelez l'abonnement en tant que ANNUAL_YEARLY_PAY, mais utilisez le nombre total de licences utilisateur actives actuelles. Il s'agit du paramètre par défaut pour les abonnements annuels actifs (payés annuellement).
RENEW_CURRENT_USERS_MONTHLY_PAY: à la fin de la période d'engagement annuel, renouvelez l'abonnement en tant que ANNUAL_MONTHLY_PAY, mais utilisez le nombre total de licences utilisateur actives actuelles. Il s'agit du paramètre par défaut pour les forfaits annuels actifs (payés mensuellement).
RENEW_ON_PROPOSED_OFFER: à la fin de l'intervalle du forfait d'engagement actuel, renouveler avec la dernière proposition de renouvellement, en définissant numberOfSeats sur le nombre de licences d'utilisateurs actifs actuelles ou sur l'engagement de l'offre proposée, selon la valeur la plus élevée.
SWITCH_TO_PAY_AS_YOU_GO: à la fin de la période d'un forfait annuel, passez à un forfait modulable.
CANCEL: à la fin d'un forfait annuel, l'abonnement est suspendu. Pour savoir comment lever une suspension, consultez le Centre d'aide pour les administrateurs.

Une réponse réussie renvoie un code d'état HTTP 201 et les paramètres de renouvellement de l'abonnement mis à jour:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Passer d'un essai sans frais à un service payant

Pour transférer immédiatement un abonnement d'essai sans frais de 30 jours vers un abonnement de service payant, si un forfait de paiement a déjà été configuré pour l'abonnement d'essai, utilisez la requête HTTP POST suivante.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/startPaidService

Remplacez les éléments suivants :

CUSTOMER_ID: nom de domaine principal du client ou identifiant unique du client.
SUBSCRIPTION_ID: identifiant de l'abonnement, qui est unique pour chaque client. Vous pouvez récupérer cette valeur à l'aide de la méthode Retrieve all reseller subscriptions (Récupérer tous les abonnements du revendeur).

Dans l'exemple suivant, customerId est défini sur C0123456 et la valeur subscriptionId est 123:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/startPaidService

Cette opération ne comporte aucun paramètre dans le corps de la requête.

Une réponse réussie renvoie un code d'état HTTP 201 et les paramètres d'abonnement mis à jour:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Passer à un abonnement inférieur ou supérieur

Vous ne pouvez pas passer à un forfait inférieur en cours de période d'abonnement annuel, ni planifier une rétrogradation à l'aide des paramètres de renouvellement. Nous vous recommandons de définir les paramètres de renouvellement pour passer à FLEXIBLE, puis de rétrograder après la période de renouvellement.

Pour passer à un abonnement supérieur ou inférieur, créez un abonnement avec le skuId auquel vous souhaitez passer.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions

Remplacez les éléments suivants :

CUSTOMER_ID: nom de domaine principal du client ou identifiant unique du client.

Cet appel met fin à l'abonnement précédent et en crée un autre.

Pour en savoir plus sur les changements de niveau d'abonnement, consultez la page "Produits et codes SKU".