Cómo recuperar y actualizar una suscripción

Después de recuperar una suscripción, puedes usar la información de la respuesta correcta para cambiar el estado de la suscripción o actualizarla. En esta página, se describen las diferentes formas en que puedes recuperar y actualizar una suscripción.

Recupera una suscripción

Para recuperar una suscripción que se pidió o transfirió correctamente, usa la siguiente solicitud GET HTTP.

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

Reemplaza lo siguiente:

  • CUSTOMER_ID: Es el nombre de dominio principal del cliente o su identificador único.
  • SUBSCRIPTION_ID: Es el identificador de suscripción que es único para cada cliente. Puedes recuperar este valor con el método Retrieve all reseller subscriptions.

Esta operación no tiene parámetros en el cuerpo de la solicitud.

Una respuesta correcta devuelve un código de estado HTTP 200 y la configuración de la suscripción. En el siguiente ejemplo de respuesta, la propiedad isInTrial es false, pero no hay ninguna propiedad trialEndTime, lo que significa que este cliente nunca tuvo una prueba gratuita de 30 días con este plan.

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

Recupera todas las suscripciones de un cliente

Para recuperar todas las suscripciones de un cliente revendedor específico que se hayan pedido o transferido correctamente, usa la siguiente solicitud HTTP GET y, luego, incluye el token de autorización:

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

Reemplaza lo siguiente:

  • CUSTOMER_ID: Es el nombre de dominio principal del cliente o su identificador único.
  • START_DATE: Es la fecha de inicio en el formato YYYY-MM-DD.
  • MAX_NUMBER: Es la cantidad máxima de resultados que se muestran en una página de respuesta.

Esta operación no tiene parámetros en el cuerpo de la solicitud.

Una respuesta correcta devuelve un código de estado HTTP 200 y una lista de las suscripciones y la configuración del cliente. Es posible que la lista de suscripciones incluya productos que no se administran en esta versión de la API de Reseller.

Si no administras a este cliente, se mostrará un error 403 "Forbidden".

Recupera todas las suscripciones transferibles de un cliente

Para recuperar todas las suscripciones de un cliente que potencialmente se podrían transferir a la administración del revendedor, usa la siguiente solicitud HTTP GET e incluye el token de autorización. El parámetro customerId es obligatorio y es el identificador único del cliente que se devuelve cuando se recupera la cuenta de un cliente de reventa. ElcustomerAuthTokenes un token de transferencia que proporciona tu cliente y que es específico para tu ID de revendedor. Una vez que el cliente lo genera, es válido durante 30 días. Para obtener más información sobre cómo los clientes generan el token, consulta Transfiere tu cuenta de Google Workspace a un revendedor.

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

Reemplaza lo siguiente:

  • CUSTOMER_ID: Es el nombre de dominio principal del cliente o su identificador único.
  • AUTH_TOKEN: Es un token de transferencia que proporciona tu cliente y que es específico para tu ID de revendedor. Después de que el cliente lo genera, es válido durante 30 días. Para obtener más información sobre cómo los clientes generan el token, consulta Transfiere tu cuenta de Google Workspace a un revendedor. Si este valor no es válido o venció, la respuesta de la API muestra un error 403 "Forbidden".
  • START_DATE: Es la fecha de inicio en el formato YYYY-MM-DD.
  • MAX_NUMBER: Es la cantidad máxima de resultados que se muestran en una página de respuesta.

Esta operación no tiene parámetros en el cuerpo de la solicitud.

Una respuesta exitosa devuelve un código de estado HTTP 200 y una lista de las suscripciones transferibles del cliente con la fecha de vencimiento del token de transferencia y la cantidad mínima de puestos necesarios en el pedido de transferencia. Es posible que un cliente tenga suscripciones adicionales que no se puedan transferir.

{
  "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 planeas transferir estas suscripciones con la operación por lotes, transfiere todas las suscripciones. Si transfieres cada suscripción de a una, se producirá un error. Además, la operación por lotes solo transfiere suscripciones con el estado ACTIVE. Para obtener más información, consulta Cómo transferir una suscripción.

Recupera todas las suscripciones de revendedor

Para recuperar todas las suscripciones que un revendedor pidió o transfirió correctamente, usa la siguiente solicitud HTTP GET e incluye el token de autorización. 

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

Reemplaza lo siguiente:

  • PREFIX: Es el comienzo del nombre del cliente cuyas suscripciones buscas.
  • TOKEN: Es un token que identifica una página específica de resultados que el servidor debe devolver.
  • MAX_NUMBER: Es la cantidad máxima de resultados que se muestran en una página de respuesta.

Esta operación puede usar el alcance de acceso de solo lectura de OAuth. customerNamePrefix, pageToken y maxResults son cadenas de consulta opcionales.

En el siguiente ejemplo, se recuperan todas las suscripciones de un revendedor que pertenecen a clientes cuyos nombres comienzan con "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"
}

Actualiza un plan de suscripción

La actualización de los planes de Google Workspace varía según el plan. Antes de actualizar un plan, considera lo siguiente:

  • Cuando creas una suscripción y el cliente cumple con los requisitos, el plan de la suscripción puede ser una prueba de 30 días. Tanto los planes de pagos flexibles como los anuales con compromiso pueden ser pruebas gratuitas de 30 días. Durante el período de prueba, puedes cambiar el plan de pagos de la suscripción a planes flexibles o de compromiso anual con la frecuencia que necesites. Sin embargo, después de que finalice la prueba y el plan se active, la actualización del plan seguirá las mismas reglas que los planes activos de otras suscripciones. Para cambiar inmediatamente una suscripción de prueba a un plan activo, inicia un servicio pagado desde una suscripción de prueba gratuita de 30 días. Para obtener más información sobre la prueba de 30 días y las reglas de calificación de los clientes, consulta el Centro de ayuda para administradores.

  • Puedes actualizar un plan flexible a un plan de compromiso anual.

  • No puedes actualizar un plan de compromiso anual.

  • No todos los planes funcionan con todos los productos. Para obtener más información sobre los productos que se usan en estos planes, consulta Productos y SKU.

Para actualizar un plan de prueba de 30 días o una suscripción a un plan flexible a un plan de compromiso anual, usa la siguiente solicitud HTTP POST:

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

Reemplaza lo siguiente:

  • CUSTOMER_ID: Es el nombre de dominio principal del cliente o su identificador único.
  • SUBSCRIPTION_ID: Es el identificador de suscripción que es único para cada cliente. Puedes recuperar este valor con el método Retrieve all reseller subscriptions.

En el siguiente ejemplo, se actualiza la suscripción con el subscriptionId con un valor de 123. El customerId es C0123456.

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

El cuerpo de la solicitud tiene lo siguiente:

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

Una respuesta correcta devuelve un código de estado HTTP 201 y la configuración actualizada del plan de suscripción:

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

Actualiza las licencias de una suscripción

La actualización de una suscripción a un plan con compromiso anual usa propiedades de suscripción diferentes a las de la actualización de una suscripción a un plan flexible de Google Workspace.

Actualiza los cupos de la suscripción de un plan anual

Para actualizar la configuración de la licencia de usuario de una suscripción al plan anual, usa la siguiente solicitud HTTP POST:

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

Reemplaza lo siguiente:

  • CUSTOMER_ID: Es el nombre de dominio principal del cliente o su identificador único.
  • SUBSCRIPTION_ID: Es el identificador de suscripción que es único para cada cliente. Puedes recuperar este valor con el método Retrieve all reseller subscriptions.

En el siguiente ejemplo, se actualiza la suscripción con el subscriptionId 123. El customerId es C0123456. El cuerpo de la solicitud difiere según el tipo de plan:

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

La suscripción a un plan de compromiso anual de Google Workspace usa este cuerpo de la solicitud para actualizar la cantidad de licencias de usuario. El valor de numberOfSeats es un total. Por ejemplo, si antes tenías 10 licencias de usuario y tienes un pedido del cliente para 5 licencias nuevas, el total en el cuerpo de la solicitud para numberOfSeats es 15, como se muestra en el siguiente ejemplo:

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

Actualiza las licencias de la suscripción a un plan flexible

La suscripción a un plan flexible de Google Workspace usa el cuerpo de la solicitud para actualizar las licencias de usuario. El valor de maximumNumberOfSeats es el total de las licencias existentes y las licencias nuevas. Es la cantidad máxima de licencias de usuario que puede aprovisionar la cuenta.

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

Una respuesta correcta devuelve un código de estado HTTP 201 y la configuración actualizada de la licencia de suscripción:

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

Actualiza la configuración de renovación de una suscripción

Para actualizar la configuración de renovación de una suscripción con compromiso anual, usa la siguiente solicitud HTTP POST:

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

Reemplaza lo siguiente:

  • CUSTOMER_ID: Es el nombre de dominio principal del cliente o su identificador único.
  • SUBSCRIPTION_ID: Es el identificador de suscripción que es único para cada cliente. Puedes recuperar este valor con el método Retrieve all reseller subscriptions.

A continuación, se muestra un ejemplo de cuerpo de solicitud:

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

El valor de la propiedad renewalType puede ser cualquiera de los siguientes:

  • AUTO_RENEW_YEARLY_PAY: Al final del intervalo de un plan con compromiso anual, renueva automáticamente el plan de la suscripción como ANNUAL_YEARLY_PAY con el mismo numberOfSeats.
  • AUTO_RENEW_MONTHLY_PAY: Al final del intervalo de un plan de compromiso anual, renueva automáticamente el plan de la suscripción como ANNUAL_MONTHLY_PAY con el mismo numberOfSeats.
  • RENEW_CURRENT_USERS_YEARLY_PAY: Al final del intervalo de un plan de compromiso anual, renueva el plan de la suscripción como ANNUAL_YEARLY_PAY, pero usa la cantidad total de licencias de usuarios activos actuales. Este es el parámetro de configuración predeterminado para los planes de compromiso anuales activos (se pagan anualmente).
  • RENEW_CURRENT_USERS_MONTHLY_PAY: Al final del intervalo de un plan de compromiso anual, renueva el plan de la suscripción como ANNUAL_MONTHLY_PAY, pero usa la cantidad total de licencias de usuarios activos actuales. Este es el parámetro de configuración predeterminado para los planes de compromiso anuales activos (se pagan mensualmente).
  • RENEW_ON_PROPOSED_OFFER: Al final del intervalo del plan de compromiso actual, se renueva con la propuesta de renovación más reciente con numberOfSeats como cantidad de licencias de usuario activo actuales o compromiso de oferta propuesto, lo que sea mayor.
  • SWITCH_TO_PAY_AS_YOU_GO: Al final del intervalo de un plan de compromiso anual, cambia el plan de compromiso anual a un plan flexible.
  • CANCEL: Al final de un intervalo del plan de compromiso anual, se suspende la suscripción. Para comprender cómo levantar una suspensión, consulta el Centro de ayuda para administradores.

Una respuesta correcta devuelve un código de estado HTTP 201 y la configuración de renovación de la suscripción actualizada:

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

Cómo iniciar el servicio pagado desde una suscripción de prueba gratuita

Para cambiar de inmediato una suscripción de prueba gratuita de 30 días a una suscripción de servicio pagado, si ya se configuró un plan de pagos para la suscripción de prueba, usa la siguiente solicitud HTTP POST. 

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

Reemplaza lo siguiente:

  • CUSTOMER_ID: Es el nombre de dominio principal del cliente o su identificador único.
  • SUBSCRIPTION_ID: Es el identificador de suscripción que es único para cada cliente. Puedes recuperar este valor con el método Retrieve all reseller subscriptions.

En el siguiente ejemplo, C0123456 es el customerId y el valor de subscriptionId es 123:

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

Esta operación no tiene parámetros en el cuerpo de la solicitud.

Una respuesta correcta devuelve un código de estado HTTP 201 y la configuración de suscripción actualizada:

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

Actualiza o cambia a una versión inferior de una suscripción

No puedes regresar a una versión anterior de los planes anuales a mitad de su período, ni puedes programar un cambio a una versión anterior con la configuración de renovación. Te recomendamos que configures los parámetros de renovación para cambiar a FLEXIBLE y, luego, cambiar a una versión inferior después del tiempo de renovación.

Para actualizar la categoría de una suscripción o cambiar a una versión inferior, crea una suscripción nueva con el skuId al que deseas actualizar la categoría o cambiar a una versión inferior.

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

Reemplaza lo siguiente:

  • CUSTOMER_ID: Es el nombre de dominio principal del cliente o su identificador único.

Esta llamada finaliza la suscripción anterior y crea una nueva.

Encontrarás más información sobre las actualizaciones y los cambios a versiones inferiores en la página Productos y SKU.