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 positive pour modifier l'état de l'abonnement ou le mettre à jour. Cette page explique comment récupérer et 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 :

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

Une réponse positive renvoie le 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&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 positive renvoie le 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 le 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 être transférés à la gestion du revendeur, utilisez la requête HTTP GET suivante et incluez le jeton d'autorisation. Le customerId est obligatoire et correspond à l'identifiant unique du client renvoyé lors de la récupération du compte d'un client revendu. Le customerAuthToken est un jeton de transfert fourni par votre client et spécifique à votre ID revendeur. Une fois généré par le client, le jeton est valide 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 et spécifique à votre ID revendeur. Une fois généré par le client, le jeton est valide 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 positive renvoie le 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 nécessaires 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 des abonnements un par un 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 tous les abonnements d'un revendeur 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?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 d'abonnement

La 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 peuvent être des essais sans frais de 30 jours. Pendant l'essai, vous pouvez modifier le forfait de l'abonnement en forfait modulable ou annuel autant de fois que nécessaire. 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 d'essai à un forfait actif, démarrez 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 Administrateur.

  • 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 modifier un forfait d'essai de 30 jours ou un abonnement à un forfait modulable en forfait 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 la valeur subscriptionId de 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 positive renvoie le code d'état HTTP 201 et les paramètres du forfait d'abonnement modifié :

{
  "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 à un forfait annuel utilise des propriétés d'abonnement différentes de celles utilisées pour modifier un abonnement à un forfait modulable Google Workspace.

Modifier les licences utilisateur d'un abonnement à un forfait annuel

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

L'exemple suivant met à jour l'abonnement avec le subscriptionId 123. Le customerId est C0123456. Le corps de la requête varie en fonction du 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 modifier 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 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 les licences utilisateur d'un abonnement à un forfait modulable

L'abonnement à un forfait modulable Google Workspace utilise le corps de la requête pour modifier 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 positive renvoie le code d'état HTTP 201 et les paramètres de licence d'abonnement modifiés :

{
  "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 modifier les paramètres de renouvellement 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/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 annuel, renouvelle 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 annuel, renouvelle 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, renouvelle le forfait de l'abonnement en tant que ANNUAL_YEARLY_PAY, mais utilise 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 annuel, renouvelle le forfait de l'abonnement en tant que ANNUAL_MONTHLY_PAY, mais utilise 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 actuel, renouvelle la dernière proposition de renouvellement avec le nombre de licences utilisateur actives actuelles ou l'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 annuel, remplace le forfait annuel par un forfait modulable.
  • CANCEL: à la fin de l'intervalle d'un forfait annuel, l'abonnement est suspendu. Pour savoir comment lever une suspension, consultez le Centre d'aide Administrateur.

Une réponse positive renvoie le code d'état HTTP 201 et les paramètres de renouvellement d'abonnement modifiés :

{
  "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 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 le customerId 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 positive renvoie le code d'état HTTP 201 et les paramètres d'abonnement modifiés :

{
  "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 annuel inférieur en cours de période, 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 sur FLEXIBLE, puis de passer à un forfait inférieur après le renouvellement.

Pour passer à un abonnement inférieur ou supérieur, créez un abonnement avec le skuId vers lequel 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.

Pour en savoir plus sur les passages à des forfaits inférieurs ou supérieurs , consultez la page Produits et SKU.