Reseller API: Manage Subscriptions

Create a subscription

To create a subscription for a customer's account that you ordered using the order a new customer account operation, use the following POST HTTP request using the authorization token described in the authorization documentation. The customerId is either the customer's primary domain name or the customer's unique identifier returned when retrieving a resold customer's account:

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

This example creates a subscription for a customer whose customerId is custId-1234. The example shows requests and responses for annual commitment, flexible, and 30-day free trial plans. For more information about which products are used by these plans, see Products And SKUs.

Creating an Annual commitment plan

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions
{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "skuId": "Google-Apps-For-Business",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY"
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10
  },
  "purchaseOrderId": "my_example.com_annual_1"
}

A successful response returns a HTTP 200 status code. Along with the status code, the response returns the new subscription's settings for an annual commitment plan. And, this subscription is not in a 30-day free trial cycle.

An example of an annual plan response:

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "subscriptionId": "123",
  "billingMethod": "ONLINE",
  "skuId": "Google-Apps-For-Business",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY",
    "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": "my_example.com_annual_1",
  "status": "ACTIVE",
  "customerDomain": "my_example.com",
  "skuName": "G Suite Basic"
}

Creating a Flexible plan

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions
{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "skuId": "Google-Apps-For-Business",
  "plan": {
    "planName": "FLEXIBLE"
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 10
  },
  "purchaseOrderId": "my_example_flex_1"
}

An example of a flexible plan response:

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "subscriptionId": "123",
  "billingMethod": "ONLINE",
  "skuId": "Google-Apps-For-Business",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "FLEXIBLE",
    "isCommitmentPlan": false
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 10,
    "licensedNumberOfSeats": 0
   },
  "trialSettings": {
    "isInTrial": false
  },
  "purchaseOrderId": "my_example_flex_1",
  "status": "ACTIVE",
  "customerDomain": "my_example.com",
  "skuName": "G Suite Basic"
}

Creating a 30-Day free trial

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions
{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "skuId": "Google-Apps-For-Business",
  "plan": {
    "planName": "TRIAL"
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 10
  },
  "purchaseOrderId": "my_example_trial_1"
}

An example of a 30-day free trial plan response:

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "subscriptionId": "123",
  "billingMethod": "ONLINE",
  "skuId": "Google-Apps-For-Business",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "TRIAL",
    "isCommitmentPlan": false
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 10,
    "licensedNumberOfSeats": 0
   },
  "trialSettings": {
    "isInTrial": true,
    "trialEndTime": "1331648420142"
  },
  "purchaseOrderId": "my_example_trial_1",
  "status": "ACTIVE",
  "customerDomain": "my_example.com",
  "skuName": "G Suite Basic"
}

Creating a Subscription with a Deal Code

Google may provide a deal code (max 100 characters) for creating subscriptions at a discounted rate. In order for a subscription to be discounted, the deal code must be provided on the subscription insert call. If the customer changes from their original SKU, the discount will be removed.

An example of an Annual commitment with deal code request :

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions
{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "skuId": "Google-Apps-For-Business",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY"
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10
  },
  "purchaseOrderId": "my_example.com_annual_1",
  "dealCode": "GOOGLE_CONTRACT_DEAL_CODE"
}

An example of an Annual commitment with deal code response :

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "subscriptionId": "123",
  "billingMethod": "ONLINE",
  "skuId": "Google-Apps-For-Business",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY",
    "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": "my_example.com_annual_1",
  "status": "ACTIVE",
  "customerDomain": "my_example.com",
  "dealCode": "GOOGLE_CONTRACT_DEAL_CODE",
  "skuName": "G Suite Basic"
}

Transfer a subscription

If you did not order the customer's account using the order a new customer account operation, use the customer's transfer token when creating a subscription for that customer.

To create a subscription for an customer account you did not order, use the following POST HTTP request and include the authorization token described in the authorization documentation. For the customerId, use the value returned in the retrieve a customer account you do not manage operation. The customerAuthToken is a transfer token provided by your customer. Once generated by the customer, it is valid for 5 days. For more information about how customers get a transfer token, see the G Suite help center. For more information about which products are used by these plans, see Products and SKUs .

POST https://www.googleapis.com/apps/reseller/v1/customers/customerId/subscriptions?customerAuthToken=token value

This example transfers the subscription of an annual commitment plan customer whose customerId is custId-1234. When transferring, the request must explicitly give the maximumNumberOfSeats. For examples of transferring a customer with a flexible or 30-day free trial plan, see the create a subscription operation. Transfers will not work with deal codes.

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions?customerAuthToken=auth token

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "skuId": "Google-Apps-For-Business",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY"
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "purchaseOrderId": "example.com_annual_1"
}

A successful response returns a HTTP 200 status code. Along with the status code, the response returns the transferred subscription's settings for an annual commitment plan. Also, this transferred subscription is not in a 30-day free trial cycle. A successful response has additional transfer information:

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "subscriptionId": "123",
  "billingMethod": "ONLINE",
  "skuId": "Google-Apps-For-Business",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY",
    "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": "example.com_annual_1",
  "status": "ACTIVE",
  "resourceUiUrl": "URL to customer's Admin console dashboard",
  "skuName": "G Suite Basic"
}

Retrieve a subscription

To retrieve a successfully ordered or transferred subscription, use the following GET HTTP request using the authorization token described in the authorization documentation. The customerId is either the customer's primary domain name or the customer's unique identifier returned when retrieving a resold customer's account. The subscriptionId can be found using the retrieve all reseller subscriptions operation:

GET https://www.googleapis.com/apps/reseller/v1/customers/customerId/subscriptions/subscriptionId

This example is retrieving a subscription whose subscriptionId value is 123. The subscription's customer has the custId-1234 customerId:

GET https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions/123

This operation has no parameters in the request body.

A successful response returns a HTTP 200 status code. Along with the status code, the response returns the subscription's settings. The isInTrial property is false but there is no trialEndTime property, meaning this customer has never been in a 30-day free trial with this plan:

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "subscriptionId": "123",
  "skuId": "Google-Apps-For-Business",
  "billingMethod": "ONLINE",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY",
    "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": "example.com_annual_1",
  "status": "ACTIVE",
  "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
  "skuName": "G Suite Basic"
}

Retrieve all subscriptions for a customer

To retrieve all of a reseller customer's subscriptions that have been successfully ordered or transferred, use the following GET HTTP request using the authorization token described in the authorization documentation. The customerId is the customer's unique identifier returned when retrieving a resold customer's account.

GET https://www.googleapis.com/apps/reseller/v1/subscriptions?customerId=customerId value&pageToken=start date&maxResults=max number

This operation has no parameters in the request body.

A successful response returns a HTTP 200 status code. Along with the status code, the response returns the list of the customer's subscriptions and settings. The list of subscriptions may include products that are not managed in this version of the API.

Retrieve all transferable subscriptions for a customer

To retrieve all of a customer's subscriptions that potentially could be transferred to the reseller's management, use the following GET HTTP request using the authorization token described in the authorization documentation . The customerId is required and is the customer's unique identifier returned when retrieving a resold customer's account. The customerAuthToken is a transfer token provided by your customer. Once generated by the customer, it is valid for 5 days. For more information about how customers get a transfer token, see the administration help center:

GET https://www.googleapis.com/apps/reseller/v1/subscriptions?customerId=customerId value&customerAuthToken=customer's transfer token&pageToken=start date&maxResults=max number

This operation has no parameters in the request body.

A successful response returns a HTTP 200 status code. Along with the status code, the response returns the list of the customer's transferable subscriptions with the expiration date of the transfer token and the minimum number of seats needed in the transfer order. A customer may hold additional subscriptions that are not transferable. The response list is composed of transferable subscriptions only. For more information about the transfer information, see the API reference.

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "432",
      "skuId": "Google-Apps-For-Business",
      "billingMethod": "ONLINE",
      "creationTime": "1331647980142",
      "plan": {
        "planName": "ANNUAL_MONTHLY_PAY",
        "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": "G Suite Basic"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "140",
      "skuId": "Google-Apps-For-Business",
      "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": "G Suite Basic"
    },
  ],
  "nextPageToken": "token"
}

Retrieve all reseller subscriptions

To retrieve all of a reseller's successfully ordered or transferred subscriptions, use the following GET HTTP request using the authorization token described in the authorization documentation. This operation can use the OAuth readonly access scope. The customerNamePrefix, pageToken, and maxResults are optional query strings:

GET https://www.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=prefix &pageToken=token&maxResults=max number

This example retrieves all of a reseller's subscriptions that belong to customers whose name begin with 'exam':

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

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-1234",
      "subscriptionId": "123",
      "skuId": "Google-Apps-For-Business",
      "creationTime": "1331647980142",
      "billingMethod": "ONLINE",
      "plan": {
        "planName": "ANNUAL_MONTHLY_PAY",
        "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": "G Suite Basic"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-5678",
      "subscriptionId": "1404686",
      "skuId": "Google-Apps-For-Business",
      "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": "G Suite Basic"
    },
  ],
  "nextPageToken": "token"
}

Update a subscription plan

To update a plan for a 30-day trial or a flexible plan subscription to an annual commitment plan, use the following POST HTTP request with the authorization token described in the authorization documentation. The customerId is either the customer's primary domain name or the customer's unique identifier returned when retrieving a resold customer's account. The subscriptionId can be found using the retrieve all reseller subscriptions operation:

POST https://www.googleapis.com/apps/reseller/v1/customers/customerId/subscriptions/subscriptionId/changePlan

Updating G Suite plans differs depending on the plan:

  • When a subscription is created and the customer qualifies, the subscription's plan can be a 30-day trial. Both the flexible and annual commitment payment plans can be 30-day free trials. During the trial, the subscription's payment plan can be changed to either flexible or annual commitment plans as often as needed. But once the trial ends and the plan becomes active, updating the plan follows the same rules as other subscriptions' active plans. To immediately move a trial subscription to an active plan, use the start a paid service from a 30-day free trial subscription operation. For more 30-day trial information and customer qualification rules, see administration help center.

  • A flexible plan can be updated to an annual commitment plan.

  • An annual commitment plan cannot be updated.

  • Not all plans work with allproducts. For more information about which products are used by these plans, see Products And SKUs.

This example updates the subscription with the subscriptionId with a value of 123. The customerId is custId-1234. For clarity, this JSON example is formatted with new line returns:

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions/123/changePlan

The request body has:

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

A successful response returns a HTTP 201 status code. Along with the status code, the response returns the updated subscription plan settings:

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "subscriptionId": "123",
  "skuId": "Google-Apps-For-Business",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY",
    "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": "G Suite Basic"
}

Update a subscription license

Updating an annual commitment plan subscription uses different subscription properties than updating a G Suite flexible plan's subscription.

Update an annual plan's subscription

To update an annual plan subscription's user license settings, use the following POST HTTP request with the authorization token described in the authorization documentation. The customerId is either the customer's primary domain name or the customer's unique identifier returned when retrieving a resold customer's account. The subscriptionId can be found using the retrieve all reseller subscriptions operation:

POST https://www.googleapis.com/apps/reseller/v1/customers/customerId/subscriptions/subscriptionId/changeSeats

This example updates the subscription with the 123 subscriptionId. The customerId is custId-1234. The body of the request differs depending on the type of plan:

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions/123/changeSeats

A G Suite annual commitment plan's subscription uses this request body to update the number of user licenses. The numberOfSeats value is a total. For example, if you previously had 10 user licenses and you have a customer order for 5 new licenses, the total in the request's body for numberOfSeats is 15:

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

Update a G Suite flexible plan's subscription

A G Suite flexible plan's subscription uses this request body to update the user licenses. The maximumNumberOfSeats value is the total of existing licenses and the new licenses. This is the maximum number of user licenses the account can provision.

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

A successful response returns a HTTP 201 status code. Along with the status code, the response returns the updated subscription license settings. This example is for an annual commitment plan:

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "subscriptionId": "123",
  "skuId": "Google-Apps-For-Business",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY",
    "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": "G Suite Basic"
}

Update a subscription's renewal settings

To update an annual commitment subscription's renewal settings, use the following POST HTTP request with the authorization token described in Authorizing requests. The customerId is either the customer's primary domain name or the customer's unique identifier returned whenretrieving a resold customer's account. The subscriptionId can be found using the retrieve all reseller subscriptions operation:

POST https://www.googleapis.com/apps/reseller/v1/customers/customerId/subscriptions/subscriptionId/changeRenewalSettings

This example changes the subscription with the 123 subscriptionId. The customerId is custId-1234:

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions/123/changeRenewalSettings

For clarity, the request body is formatted with new line returns:

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

The renewalType property's value can be:

  • AUTO_RENEW_YEARLY_PAY — At the end of an annual commitment plan's interval, automatically renew the subscription's plan as ANNUAL_YEARLY_PAY with the same numberOfSeats.
  • AUTO_RENEW_MONTHLY_PAY - At the end of an annual commitment plan's interval, automatically renew the subscriptions's plan as ANNUAL_MONTHLY_PAY with the same numberOfSeats.
  • RENEW_CURRENT_USERS_YEARLY_PAY — At the end of an annual commitment plan's interval, renew the subscription's plan as ANNUAL_YEARLY_PAY but use the total number of current active user licenses.
  • RENEW_CURRENT_USERS_MONTHLY_PAY - At the end of an annual commitment plan's interval, renew the subscription's plan as ANNUAL_MONTHLY_PAY but use the total number of current active user licenses.
  • SWITCH_TO_PAY_AS_YOU_GO — At the end of an annual commitment plan's interval, change the annual commitment plan to a flexible plan. This is the default setting for active annual commitment plans.
  • CANCEL — At the end of an annual commitment plan interval, the customer's account is suspended. To understand how to lift a suspension, see the administration help center.

A successful response returns a HTTP 201 status code. Along with the status code, the response returns the updated subscription renewal settings:

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "subscriptionId": "123",
  "skuId": "Google-Apps-For-Business",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY",
    "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": "G Suite Basic"
}

Start paid service from a 30-day free trial subscription

To immediately move a 30-day free trial subscription to paid service subscription, use the following POST HTTP request with the authorization token described in [Authorizing requests]((/admin-sdk/reseller/v1/how- tos/authorizing). The customerId is either the customer's primary domain name or the customer's unique identifier returned when retrieving a resold customer's account. The subscriptionId can be found using the retrieve all reseller subscriptions operation.

POST https://www.googleapis.com/apps/reseller/v1/customers/customerId/subscriptions/subscriptionId/startPaidService

This example has the custId-1234 customerId and the subscriptionId value of 123:

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions/123/startPaidService

This operation has no parameters in the request body.

A successful response returns a HTTP 201 status code. Along with the status code, the response returns the updated subscription settings:

{
  "kind": "reseller#subscription",
  "customerId": "custId-1234",
  "subscriptionId": "123",
  "skuId": "Google-Apps-For-Business",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY",
    "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": "G Suite Basic"
}

Suspend a subscription

To suspend a subscription, utilize the following POST HTTP request with the authorization token described in Authorizing requests. The customerId is either the customer's primary domain name or the customer's unique identifier returned when retrieving a resold customer's account. The subscriptionId can be found using the retrieve all reseller subscriptions operation.

It is important to note that:

  • Subscriptions can be suspended for up to 60 days.
  • You can use this method to suspend a paid subscription that is currently in the ACTIVE state.
  • For FLEXIBLE subscriptions, billing is paused.
  • For ANNUAL_MONTHLY_PAY or ANNUAL_YEARLY_PAY subscriptions, this does not adjust the annual renewal date that was originally committed to.
  • This method will fail for TRIAL subscriptions and other free subscription types.

Request Signature:

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions/123/suspend

Activate a subscription

To activate a subscription, utilize the following POST HTTP request with the authorization token described in Authorizing requests. The customerId is either the customer's primary domain name or the customer's unique identifier returned when retrieving a resold customer's account. The subscriptionId can be found using the retrieve all reseller subscriptions operation.

POST https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions/123/activate

Cancel a subscription or customer

To immediately cancel a non G Suite subscription, use the following DELETE HTTP request with a deletionType of 'transfer_to_direct' with the authorization token described in Authorizing requests. The customerId is either the customer's primary domain name or the customer's unique identifier returned when retrieving a resold customer's account. The subscriptionId can be found using the retrieve all reseller subscriptions operation.

This method allows for an unobtrusive way for resellers to cancel a customer. With this deletionType the customer is immediately transferred to a direct billing relationship with Google and is given a short amount of time with no service interruption. The customer can then choose to set up billing directly with Google by using a credit card, or they can transfer to another reseller.

This example cancels the subscription and transfers the customer to direct with the 123 subscriptionId for the customer whose customerId is custId-1234:

DELETE https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions/123?deletionType=transfer_to_direct

Delete a subscription (Deprecated)

To immediately delete a non G Suite subscription, use the following DELETE HTTP request with the authorization token described in Authorizing requests. The customerId is either the customer's primary domain name or the customer's unique identifier returned when retrieving a resold customer's account. The subscriptionId can be found using the retrieve all reseller subscriptions operation.

It is important to note that:

  • You must understand the implications of cancelling and downgrading products. For more information, see Products and SKUs.
  • When the deletionType query string is cancel: This operation cancels the subscription immediately. This deletionType does not apply to a G Suite subscription.
  • When the deletionType query string is suspend: The G Suite account is suspended for 4 days and then cancelled. Once suspended, an administrator has access to the suspended account, but the account users cannot access their services.

Request signature:

DELETE https://www.googleapis.com/apps/reseller/v1/customers/customerId/subscriptions/subscriptionId?deletionType=cancel or suspend

This example cancels the subscription with the 123 subscriptionId for the customer whose customerId is custId-1234:

DELETE https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions/123?deletionType=cancel

This example cancels a G Suite subscription with the 321 subscriptionId for the customer whose customerId is custId-1234. The customer will be suspended for four days, and then cancelled.:

DELETE https://www.googleapis.com/apps/reseller/v1/customers/custId-1234/subscriptions/321?deletionType=suspend

Error syntax

If a request is not successful, the API service's response returns an error. For a JSON response, the error syntax is:

{
  error: {
    errors: [
      {
        "domain": string,
        "reason": string,
        "message": string
      }
     ],
    "code": string,
    "message": string
 }
}

Send feedback about...

G Suite Reseller API
G Suite Reseller API