Reseller API: Manage subscriptions

Create a subscription

To create a subscription for a newly created customer's account, use the following POST HTTP request with the authorization token described in 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:

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

Note: If you did not order this customer's account, you can transfer a subscription.

Note: Customers with customerType = 'team' can only purchase Essentials and Enterprise Essentials editions of Google Workspace. If you try to purchase any of the other Workspace subscriptions, you will see an error—Customer is not eligible to purchase this subscription. Customers purchasing Essentials or usage-based subscriptions may not be able to handle Annual Commitment plans and will have limited upgrade and downgrade options.

The examples below create subscriptions for a customer whose customerId is C0123456. They show requests and responses for annual commitment, flexible, and 30-day free trial plans. For more information about the products that these plans use, see Products And SKUs.

Creating an annual commitment plan

Here is an example request to create an annual commitment subscription:

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

A successful response returns a HTTP 200 status and the new subscription's settings for an annual commitment plan.

Note: For annual commitment plan subscriptions, not all SKUs have the same default renewal settings. It is recommended to always pass renewalSettings.

Note: ANNUAL_MONTHLY_PAY is returned as ANNUAL in all API responses.

An example of an annual plan response is below:

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

Creating a flexible plan

Here is an example request to create a flexible subscription:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions
{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "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 is below:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "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 free trial

Here is an example request to create a 30-day free trial:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions
{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "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 is below:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "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 for creating subscriptions at a discounted rate. To discount a subscription, you must provide the deal code in the subscription insert call. If the customer changes from their original SKU, the discount is removed.

Deal codes don't take effect when:

Creating trial plans

• Trial plans can only be given a discount when upgrading to a paid plan by providing a deal code via the `changePlan` call.

Transferring subscriptions

• Regular pricing takes effect if a discounted subscription is transferred.

An example of a request to create a discounted annual commitment subscription is below:

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

An example of a response for a discounting annual commitment subscription is below:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "billingMethod": "ONLINE",
  "skuId": "Google-Apps-For-Business",
  "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": "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 a customer account you did not order, use the following POST HTTP request. The customerAuthToken is a transfer token provided by your customer. Once the customer generates the token, it is valid for 14 days.

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

For more information about how customers get a transfer token, see the Google Workspace help center. For more information about which products are used by these plans, see Products and SKUs .

Note: when transferring a legacy SKU, subscriptions.list returns a skuId of the SKU that needs to be transferred. The skuId of the SKU that the customer actually has is returned as transferInfo.currentLegacySkuId. You can find all skuIds in the Products and SKUs page.

The example below transfers the subscription of an annual commitment plan customer whose customerId is C0123456. For examples of transferring a customer with a flexible or 30-day free trial plan, see Manage customers. Transfers don't work with deal codes.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions?customerAuthToken=auth token
{
  "customerId": "C0123456",
  "skuId": "Google-Apps-For-Business",
  "plan": {
    "planName": "ANNUAL_MONTHLY_PAY"
  },
  "seats": {
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "purchaseOrderId": "example.com_annual_1"
}

Note: If transferring a Google Workspace subscription with an associated Google Drive or Google Vault subscription, use the batch operation to transfer all subscriptions with an ACTIVE status. Transferring each subscription one-by-one results in an error.

Note: Transfer of suspended subscriptions are allowed only if the suspension reason is PENDING_TOS_ACCEPTANCE, TRIAL_ENDED, or RENEWAL_WITH_TYPE_CANCEL.

A successful response returns an HTTP 200 status code and the transferred subscription's settings for an annual commitment plan:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "billingMethod": "ONLINE",
  "skuId": "Google-Apps-For-Business",
  "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": "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. The subscriptionId can be found using the retrieve all reseller subscriptions operation.

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

This operation has no parameters in the request body.

A successful response returns an HTTP 200 status code and 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": "C0123456",
  "subscriptionId": "123",
  "skuId": "Google-Apps-For-Business",
  "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": "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://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=customerId value&pageToken=start date&maxResults=max number

Note: This operation is used for a specific customer. The customerNamePrefix argument used in the retrieving of all reseller subscriptions operation is ignored when retrieving information about a specific resold customer.

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.

Note: If the customer identified in the customerId is not managed by this reseller, a 403 "Forbidden" error is returned.

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. ThecustomerAuthToken is a transfer token provided by your customer that is specific to your reseller ID. Once generated by the customer, it is valid for 14 days. For more information about how customers generate the token, see Transfer your Google Workspace account to a reseller.

GET https://reseller.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.

Note: If the customerAuthToken is not valid or has expired, the API response returns a 403 "Forbidden" error.

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.

Note: If transferring these subscriptions using the batch operation, transfer all of the subscriptions. Transferring each subscription one-by-one results in an error. In addition, the batch operation only transfers subscriptions with an ACTIVE status.

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "432",
      "skuId": "Google-Apps-For-Business",
      "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": "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://reseller.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://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=exam

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "C0123456",
      "subscriptionId": "123",
      "skuId": "Google-Apps-For-Business",
      "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": "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:

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

Updating Google Workspace 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 the 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 all products. 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 C0123456.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/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": "C0123456",
  "subscriptionId": "123",
  "skuId": "Google-Apps-For-Business",
  "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": "G Suite Basic"
}

Update a subscription's seats

Updating an annual commitment plan subscription uses different subscription properties than updating a Google Workspace 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:

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

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

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

A Google Workspace 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 Google Workspace flexible plan's subscription

A Google Workspace 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:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "Google-Apps-For-Business",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "FLEXIBLE",
    "isCommitmentPlan": false
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 15,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "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:

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

Here is an example request body:

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

The renewalType property's value can be any of the following:

• 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. This is the default setting for active annual commitment plans (paid yearly).
• 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. This is the default setting for active annual commitment plans (paid monthly).
• 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.
• CANCEL: At the end of an annual commitment plan interval, the subscription is suspended. To understand how to lift a suspension, see the administration help center.

Note: All API responses return both AUTO_RENEW_MONTHLY_PAY and AUTO_RENEW_YEARLY_PAY as AUTO_RENEW and both RENEW_CURRENT_USERS_MONTHLY_PAY and RENEW_CURRENT_USERS_YEARLY_PAY as RENEW_CURRENT_USERS.

A successful response returns a HTTP 201 status code and the updated subscription renewal settings:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "Google-Apps-For-Business",
  "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": "G Suite Basic"
}

Start paid service from a free trial subscription

To immediately move a 30-day free trial subscription to paid service subscription, use the following POST HTTP request.

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

Note: This operation is only applicable if a payment plan has already been set up for the trial subscription.

This example has the C0123456 customerId and the subscriptionId value of 123:

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

This operation has no parameters in the request body.

A successful response returns a HTTP 201 status code and the updated subscription settings:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "Google-Apps-For-Business",
  "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": "G Suite Basic"
}

Upgrade or downgrade a subscription

To upgrade or downgrade a subscription, create a new subscription with the skuId you want to upgrade or downgrade to.

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

This call terminates the previous subscription and creates a new one.

You cannot downgrade annual plans in the middle of their term, and you cannot schedule a downgrade via renewal settings. We recommend that you set renewal settings to switch to FLEXIBLE and then downgrade after renewal time.

Find more information about upgrades and downgrades on the Products & SKUs page.

Suspend a subscription

To suspend a subscription, use the following POST HTTP request:

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

It is important to note the following:

• 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, also note the following:
  • Suspending the subscription does not change the renewal date.
  • A suspended subscription does not renew. If you activate the subscription after the original renewal date, a new annual subscription is created, starting on the day of activation.
• This method fails for TRIAL subscriptions and other free subscription types.

Activate a subscription

To activate a suspended subscription, use the following POST HTTP request:

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

Note: This method can't activate a subscription that is suspended for abuse or for pending terms of service acceptance.

Cancel a Google Workspace subscription

To immediately cancel a Google Workspace subscription, use the following DELETE HTTP request with a deletionType='transfer_to_direct':

DELETE https://reseller.googleapis.com/apps/reseller/v1/customers/customerId/subscriptions/subscriptionId?deletionType=transfer_to_direct

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 either set up billing directly with Google by using a credit card or transfer to another reseller.

Note: If a customer contains multiple subscriptions, all subscriptions need to be provided as a batch request so that they can be processed in a single transaction.

Delete a subscription (Deprecated)

Warning: Making a DELETE call with deletionType='cancel' is deprecated and suspension is the recommended option.

To immediately delete a non Google Workspace subscription, use the following DELETE HTTP request:

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

It is important to note the following:

• 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 Google Workspace subscription.

Error syntax

If a request is unsuccessful, the API service's response returns an error. For a JSON response, the error syntax is shown below:

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

See also:

• Reseller API common errors
• Directory API common errors