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 explique les différentes façons de récupérer et de modifier un abonnement.

Récupérer un abonnement

Pour récupérer un abonnement commandé ou transféré, 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 :

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 définie sur false, mais il n'y a pas de propriété trialEndTime. Cela 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" s'affiche.

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

Pour récupérer tous les abonnements d'un client qui pourraient ê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 30 jours. Pour savoir comment 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 savoir comment 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 licences requises dans l'ordre de transfert. Il est possible qu'un client détienne d'autres abonnements non 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 Transférer un abonnement.

Récupérer tous les abonnements de revendeur

Pour récupérer toutes les souscriptions commandées ou transférées 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 champ d'application 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 qui appartiennent à des clients dont le nom commence par &39;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 d'abonnement

La procédure de modification des forfaits Google Workspace varie selon le forfait. Avant de modifier un forfait, 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 annuels avec engagement peuvent être des essais sans frais de 30 jours. Pendant la période d'essai, vous pouvez modifier le forfait de l'abonnement pour choisir un forfait modulable ou un engagement 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 les forfaits actifs des autres abonnements. Pour passer immédiatement d'un abonnement à l'essai à un forfait actif, démarrez un service payant à partir d'un abonnement à l'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 avec engagement annuel.

  • Vous ne pouvez pas modifier un forfait avec engagement annuel.

  • Tous les forfaits ne fonctionnent pas avec tous les produits. Pour en savoir plus sur les produits utilisés par ces forfaits, consultez Produits et SKU.

Pour passer d'un forfait d'essai de 30 jours ou d'un forfait flexible à un 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 :

L'exemple suivant met à jour l'abonnement avec le subscriptionId et la valeur 123. Le customerId est 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 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 le nombre de licences d'un abonnement

La mise à jour d'un abonnement à un forfait avec engagement annuel utilise des propriétés d'abonnement différentes de celles utilisées pour la mise à jour d'un abonnement à un forfait modulable Google Workspace.

Modifier le nombre de licences d'un abonnement annuel

Pour mettre à jour les paramètres de licence utilisateur d'un abonnement 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 :

L'exemple suivant met à jour l'abonnement avec le subscriptionId 123. Le customerId est 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 à un forfait annuel Google Workspace 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 reçu une commande client pour 5 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
}

Modifier le nombre de licences utilisateur pour un abonnement à un forfait modulable

L'abonnement à 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 :

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 l'intervalle d'un forfait avec engagement annuel, renouvelez automatiquement le forfait de l'abonnement en tant que ANNUAL_YEARLY_PAY avec le même numberOfSeats.
  • AUTO_RENEW_MONTHLY_PAY : à la fin de l'intervalle d'un forfait avec 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 l'intervalle d'un forfait avec engagement annuel, renouvelez le forfait de 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 forfaits annuels actifs (payés annuellement).
  • RENEW_CURRENT_USERS_MONTHLY_PAY : à la fin de l'intervalle d'un forfait avec engagement annuel, renouvelez le forfait de 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 avec engagement actuel, renouvelez l'engagement en fonction de la dernière proposition de renouvellement, avec numberOfSeats comme nombre de licences utilisateur actives actuelles ou comme engagement de l'offre proposée, selon la valeur la plus élevée.
  • SWITCH_TO_PAY_AS_YOU_GO : à la fin de l'intervalle d'un forfait avec engagement annuel, passez au forfait modulable.
  • CANCEL : à la fin d'un intervalle de 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 abonnement d'essai sans frais à un service payant

Pour passer immédiatement d'un abonnement d'essai sans frais de 30 jours à un abonnement à un service payant, si un forfait 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 :

Dans l'exemple suivant, C0123456 est la valeur customerId et 123 est la valeur subscriptionId :

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 supérieur ou inférieur

Vous ne pouvez pas passer à un forfait annuel inférieur en cours de période, ni planifier un changement de forfait à l'aide des paramètres de renouvellement. Nous vous recommandons de définir les paramètres de renouvellement sur FLEXIBLE, puis de passer à un forfait inférieur après la date 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 SKU.