Récupérer et mettre à jour un abonnement

Après avoir récupéré un abonnement, vous pouvez utiliser les informations de la réponse positive pour modifier l'état de l'abonnement ou le mettre à jour. Cette page décrit 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é, 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 d'abonnement unique pour chaque client. Vous pouvez récupérer cette valeur à l'aide de la méthode Récupérer tous les abonnements revendeur.

Le corps de la requête ne comporte aucun paramètre pour cette opération.

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 le 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 bien é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.

Le corps de la requête ne comporte aucun paramètre pour cette opération.

Une réponse réussie renvoie un code d'état HTTP 200, ainsi que la 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 l'accès à un 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 qui pourraient potentiellement être transférés au revendeur, utilisez la requête HTTP GET suivante et incluez le jeton d'autorisation. Le customerId est obligatoire. Il s'agit de l'identifiant unique du client, renvoyé lors de la récupération du compte d'un client indirect. 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 valide pendant 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 et spécifique à votre ID revendeur. Une fois généré par le client, il est valide 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.

Le corps de la requête ne comporte aucun paramètre pour cette opération.

Une réponse réussie renvoie un code d'état HTTP 200 et la liste des abonnements transférables du client, ainsi que la date d'expiration du jeton de transfert et le nombre minimal de licences requises dans l'ordre 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 individuellement de chaque abonnement génère une erreur. De plus, l'opération par lot ne transfère que les abonnements présentant l'état ACTIVE. Pour en savoir plus, consultez Transférer un abonnement.

Récupérer tous les abonnements revendeur

Pour récupérer tous les abonnements d'un revendeur 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?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 spécifique de résultats 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 OAuth en lecture seule. 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 abonnement

La mise à jour des forfaits Google Workspace diffère selon les forfaits. Avant de mettre à jour un plan, tenez compte des points suivants:

  • Lorsque vous créez un abonnement et que le client est éligible, le forfait peut correspondre à un essai de 30 jours. Les forfaits modulables et annuels avec engagement peuvent correspondre à des essais sans frais de 30 jours. Au cours de la période d'essai, vous pouvez modifier le forfait de l'abonnement pour passer à un forfait modulable ou annuel aussi souvent que nécessaire. Toutefois, une fois la période d'essai terminée et le forfait activé, la mise à jour suit les mêmes règles que les forfaits actifs des autres abonnements. Pour transférer immédiatement un abonnement d'essai vers un forfait actif, démarrez un service payant à partir d'un essai sans frais de 30 jours. Pour obtenir plus d'informations sur les essais de 30 jours et connaître les règles d'éligibilité des clients, consultez le Centre d'aide pour l'administration.

  • Vous pouvez passer d'un forfait modulable à un forfait annuel.

  • Vous ne pouvez pas modifier un forfait 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 modulable à 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 :

  • CUSTOMER_ID: nom de domaine principal du client ou identifiant unique du client.
  • SUBSCRIPTION_ID: identifiant d'abonnement unique pour chaque client. Vous pouvez récupérer cette valeur à l'aide de la méthode Récupérer tous les abonnements revendeur.

L'exemple suivant met à jour l'abonnement avec le subscriptionId avec une valeur de 123. customerId est C0123456.

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

Le corps de la requête se présente comme suit:

{
  "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 de 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 associées à un abonnement

Modifier un abonnement avec un forfait annuel n'utilise pas les mêmes propriétés que la mise à jour d'un forfait modulable Google Workspace.

Modifier les licences utilisateur associées à un forfait annuel

Pour mettre à jour les paramètres de licence utilisateur d'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 d'abonnement unique pour chaque client. Vous pouvez récupérer cette valeur à l'aide de la méthode Récupérer tous les abonnements revendeur.

L'exemple suivant met à jour l'abonnement avec la valeur subscriptionId 123. customerId est C0123456. Le corps de la requête varie selon le type de forfait:

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

L'abonnement d'un forfait avec engagement 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 commandé 5 nouvelles licences à un client, le total de 15 licences dans le corps de la requête pour numberOfSeats est de 15, comme illustré dans l'exemple suivant:

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

Modifier les licences utilisateur associées à un 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"
}

Mettre à jour 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 d'abonnement unique pour chaque client. Vous pouvez récupérer cette valeur à l'aide de la méthode Récupérer tous les abonnements 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 l'intervalle d'un forfait annuel, renouvelez automatiquement 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 annuel, renouvelez automatiquement le forfait de l'abonnement en tant que ANNUAL_MONTHLY_PAY avec le même numberOfSeats.
  • RENEW_CURRENT_USERS_YEARLY_PAY: à la fin de l'intervalle d'un forfait annuel, renouvelez l'abonnement en tant que ANNUAL_YEARLY_PAY, mais utilisez le nombre total de licences utilisateur actuellement actives. Il s'agit du paramètre par défaut pour les forfaits avec engagement annuel actifs (paiements annuels).
  • RENEW_CURRENT_USERS_MONTHLY_PAY: à la fin de l'intervalle d'un forfait annuel, renouvelez l'abonnement en tant que ANNUAL_MONTHLY_PAY, mais utilisez le nombre total de licences utilisateur actuellement actives. Il s'agit du paramètre par défaut pour les forfaits avec engagement annuel actifs (paiements mensuels).
  • RENEW_ON_PROPOSED_OFFER: à la fin de l'intervalle du forfait d'engagement actuel, renouvelez l'engagement selon la dernière proposition de renouvellement avec le nombre de licences utilisateur actif (numberOfSeats) correspondant au nombre de licences utilisateur actives ou l'engagement proposé (selon la valeur la plus élevée).
  • SWITCH_TO_PAY_AS_YOU_GO: à la fin de l'intervalle d'un forfait annuel, remplacez le forfait annuel par un forfait modulable.
  • CANCEL: à la fin de l'intervalle du forfait annuel, l'abonnement est suspendu. Pour savoir comment lever une suspension, consultez le Centre d'aide pour l'administration.

Une réponse réussie renvoie un code d'état HTTP 201 et les paramètres de renouvellement 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"
}

Démarrer un service payant à partir d'un abonnement d'essai sans frais

Pour transformer immédiatement un abonnement d'essai sans frais de 30 jours en abonnement de 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 :

  • CUSTOMER_ID: nom de domaine principal du client ou identifiant unique du client.
  • SUBSCRIPTION_ID: identifiant d'abonnement unique pour chaque client. Vous pouvez récupérer cette valeur à l'aide de la méthode Récupérer tous les abonnements revendeur.

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

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

Le corps de la requête ne comporte aucun paramètre pour cette opération.

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 au cours de leur période d'engagement, ni planifier un passage à un forfait inférieur à l'aide des paramètres de renouvellement. Nous vous recommandons de définir les paramètres de renouvellement de manière à passer à FLEXIBLE, puis à passer à un forfait inférieur après la date de renouvellement.

Pour passer à un forfait supérieur ou inférieur, créez un autre abonnement avec le niveau skuId que vous souhaitez utiliser.

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 le passage à un niveau supérieur et inférieur, consultez la page "Produits et SKU".