구독 검색 및 업데이트

정기 결제를 가져온 후 성공적인 응답의 정보를 사용하여 정기 결제의 상태를 변경하거나 정기 결제를 업데이트할 수 있습니다. 이 페이지에서는 정기 결제를 가져오고 업데이트할 수 있는 다양한 방법을 중점적으로 다룹니다.

구독 가져오기

주문 또는 이전이 완료된 정기 결제를 가져오려면 다음 GET HTTP 요청을 사용하세요.

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

다음을 바꿉니다.

  • CUSTOMER_ID: 고객의 기본 도메인 이름 또는 고객의 고유 식별자입니다.
  • SUBSCRIPTION_ID: 각 고객에게 고유한 정기 결제 식별자입니다. 모든 리셀러 구독 검색 메서드를 사용하여 이 값을 검색할 수 있습니다.

이 작업에는 요청 본문에 매개변수가 없습니다.

성공적인 응답은 HTTP 200 상태 코드와 정기 결제의 설정을 반환합니다. 다음 예시 응답에서 isInTrial 속성은 false이지만 trialEndTime 속성이 없습니다. 즉, 이 고객이 이 요금제로 30일 무료 체험을 사용한 적이 없다는 의미입니다.

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

고객의 모든 구독 가져오기

주문 또는 이전이 완료된 특정 리셀러 고객의 모든 구독을 가져오려면 다음 GET HTTP 요청을 사용하고 승인 토큰을 포함하세요.

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

다음을 바꿉니다.

  • CUSTOMER_ID: 고객의 기본 도메인 이름 또는 고객의 고유 식별자입니다.
  • START_DATE: YYYY-MM-DD 형식의 시작일입니다.
  • MAX_NUMBER: 응답 페이지에서 반환되는 최대 결과 수입니다.

이 작업에는 요청 본문에 매개변수가 없습니다.

응답에 HTTP 200 상태 코드와 고객의 구독 및 설정 목록이 반환됩니다. 정기 결제 목록에는 이 버전의 리셀러 API에서 관리되지 않는 제품이 포함될 수 있습니다.

이 고객을 관리하지 않으면 403 "Forbidden" 오류가 반환됩니다.

고객의 이전 가능한 모든 구독 가져오기

리셀러의 관리로 이전될 수 있는 고객의 모든 구독을 가져오려면 다음 GET HTTP 요청을 사용하고 승인 토큰을 포함하세요. customerId은 필수이며 재판매된 고객의 계정을 가져올 때 반환되는 고객의 고유 식별자입니다. customerAuthToken은 고객이 제공한 이전 토큰으로, 리셀러 ID에만 해당합니다. 고객이 생성한 후 30일 동안 유효합니다. 고객이 토큰을 생성하는 방법에 대한 자세한 내용은 Google Workspace 계정을 리셀러로 이전하기를 참고하세요.

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

다음을 바꿉니다.

  • CUSTOMER_ID: 고객의 기본 도메인 이름 또는 고객의 고유 식별자입니다.
  • AUTH_TOKEN: 고객이 제공한 이전 토큰으로, 리셀러 ID에만 해당합니다. 고객이 생성한 후 30일 동안 유효합니다. 고객이 토큰을 생성하는 방법에 관한 자세한 내용은 Google Workspace 계정을 리셀러로 이전하기를 참고하세요. 이 값이 유효하지 않거나 만료된 경우 API 응답은 403 "Forbidden" 오류를 반환합니다.
  • START_DATE: YYYY-MM-DD 형식의 시작일입니다.
  • MAX_NUMBER: 응답 페이지에서 반환되는 최대 결과 수입니다.

이 작업에는 요청 본문에 매개변수가 없습니다.

성공적인 응답은 HTTP 200 상태 코드와 이전 토큰의 만료일, 이전 주문에 필요한 최소 좌석 수가 포함된 고객의 이전 가능한 구독 목록을 반환합니다. 고객이 이전할 수 없는 추가 구독을 보유하고 있을 수 있습니다.

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

일괄 작업을 사용하여 이러한 구독을 이전할 계획이라면 모든 구독을 이전하세요. 각 구독을 하나씩 이전하면 오류가 발생합니다. 또한 일괄 작업은 ACTIVE 상태의 구독만 이전합니다. 자세한 내용은 구독 이전을 참고하세요.

모든 리셀러 구독 가져오기

리셀러가 주문하거나 이전한 모든 구독을 가져오려면 다음 GET HTTP 요청을 사용하고 승인 토큰을 포함하세요. 

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

다음을 바꿉니다.

  • PREFIX: 정기 결제를 찾고 있는 고객 이름의 시작 부분입니다.
  • TOKEN: 서버에서 반환해야 하는 특정 결과 페이지를 식별하는 토큰입니다.
  • MAX_NUMBER: 응답 페이지에서 반환되는 최대 결과 수입니다.

이 작업은 OAuth 읽기 전용 액세스 범위를 사용할 수 있습니다. customerNamePrefix, pageToken, maxResults은 선택적 쿼리 문자열입니다.

다음 예에서는 이름이 '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"
}

구독 요금제 업데이트

Google Workspace 요금제 업데이트는 요금제에 따라 다릅니다. 요금제를 업데이트하기 전에 다음 사항을 고려하세요.

  • 구독을 만들 때 고객이 자격을 갖춘 경우 구독의 요금제를 30일 무료 체험으로 설정할 수 있습니다. 탄력 요금제와 연간 약정 요금제 모두 30일 무료 체험판으로 사용할 수 있습니다. 무료 체험 기간 동안 필요에 따라 구독의 요금제를 탄력 요금제 또는 연간 약정 요금제로 변경할 수 있습니다. 하지만 체험이 종료되고 요금제가 활성화된 후에는 요금제 업데이트가 다른 구독의 활성 요금제와 동일한 규칙을 따릅니다. 체험 구독을 활성 요금제로 즉시 전환하려면 30일 무료 체험 구독에서 유료 서비스를 시작하세요. 30일 무료 체험 및 고객 자격 요건에 관한 자세한 내용은 관리 고객센터를 참고하세요.

  • 탄력 요금제를 연간 약정 요금제로 업데이트할 수 있습니다.

  • 연간 약정 요금제는 업데이트할 수 없습니다.

  • 일부 요금제는 일부 제품에서 작동하지 않습니다. 이 요금제에서 사용되는 제품에 대한 자세한 내용은 제품 및 SKU를 참고하세요.

30일 무료 체험 또는 유연한 요금제 구독을 연간 약정 요금제로 업데이트하려면 다음 POST HTTP 요청을 사용하세요.

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

다음을 바꿉니다.

  • CUSTOMER_ID: 고객의 기본 도메인 이름 또는 고객의 고유 식별자입니다.
  • SUBSCRIPTION_ID: 각 고객에게 고유한 정기 결제 식별자입니다. 모든 리셀러 구독 검색 메서드를 사용하여 이 값을 검색할 수 있습니다.

다음 예시에서는 값이 123인 subscriptionId로 구독을 업데이트합니다. customerId은 C0123456입니다.

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

요청 본문에는 다음이 포함됩니다.

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

성공적인 응답은 HTTP 201 상태 코드를 반환하고 업데이트된 요금제 설정을 반환합니다.

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

구독의 좌석 업데이트

연간 약정 요금제 구독을 업데이트하는 것은 Google Workspace 탄력 요금제 구독을 업데이트하는 것과 다른 구독 속성을 사용합니다.

연간 요금제 구독의 시트 업데이트

연간 요금제 구독의 사용자 라이선스 설정을 업데이트하려면 다음 POST HTTP 요청을 사용하세요.

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

다음을 바꿉니다.

  • CUSTOMER_ID: 고객의 기본 도메인 이름 또는 고객의 고유 식별자입니다.
  • SUBSCRIPTION_ID: 각 고객에게 고유한 정기 결제 식별자입니다. 모든 리셀러 구독 검색 메서드를 사용하여 이 값을 검색할 수 있습니다.

다음 예시에서는 123 subscriptionId로 정기 결제를 업데이트합니다. customerId는 C0123456입니다. 요청 본문은 요금제 유형에 따라 다릅니다.

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

Google Workspace 연간 약정 요금제의 구독은 이 요청 본문을 사용하여 사용자 라이선스 수를 업데이트합니다. numberOfSeats 값은 합계입니다. 예를 들어 이전에 사용자 라이선스가 10개 있었고 새 라이선스 5개에 대한 고객 주문이 있는 경우 요청 본문의 numberOfSeats 총계는 다음 예와 같이 15입니다.

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

탄력 요금제 구독의 좌석 업데이트

Google Workspace 탄력 요금제 구독은 요청 본문을 사용하여 사용자 라이선스를 업데이트합니다. maximumNumberOfSeats 값은 기존 라이선스와 새 라이선스의 합계입니다. 계정에서 프로비저닝할 수 있는 최대 사용자 라이선스 수입니다.

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

응답에 HTTP 201 상태 코드와 업데이트된 정기 결제 라이선스 설정이 반환됩니다.

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

구독의 갱신 설정 업데이트

연간 약정 구독의 갱신 설정을 업데이트하려면 다음 POST HTTP 요청을 사용하세요.

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

다음을 바꿉니다.

  • CUSTOMER_ID: 고객의 기본 도메인 이름 또는 고객의 고유 식별자입니다.
  • SUBSCRIPTION_ID: 각 고객에게 고유한 정기 결제 식별자입니다. 모든 리셀러 구독 검색 메서드를 사용하여 이 값을 검색할 수 있습니다.

다음은 요청 본문의 예입니다.

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

renewalType 속성의 값은 다음 중 하나일 수 있습니다.

  • AUTO_RENEW_YEARLY_PAY: 연간 약정 요금제의 간격이 끝나면 동일한 numberOfSeats로 정기 결제의 요금제를 ANNUAL_YEARLY_PAY로 자동 갱신합니다.
  • AUTO_RENEW_MONTHLY_PAY: 연간 약정 요금제의 간격이 끝나면 구독의 요금제를 동일한 numberOfSeats로 ANNUAL_MONTHLY_PAY로 자동 갱신합니다.
  • RENEW_CURRENT_USERS_YEARLY_PAY: 연간 약정 요금제의 간격이 끝나면 구독 요금제를 ANNUAL_YEARLY_PAY로 갱신하되 현재 활성 사용자 라이선스의 총수를 사용합니다. 활성 연간 약정 요금제 (연간 결제)의 기본 설정입니다.
  • RENEW_CURRENT_USERS_MONTHLY_PAY: 연간 약정 요금제의 간격이 끝나면 구독 요금제를 ANNUAL_MONTHLY_PAY로 갱신하되 현재 활성 사용자 라이선스의 총수를 사용합니다. 활성 연간 약정 요금제 (매월 결제)의 기본 설정입니다.
  • RENEW_ON_PROPOSED_OFFER: 현재 약정 요금제의 간격이 끝나면 현재 활성 사용자 라이선스 수 또는 제안된 혜택 약정 중 더 높은 값으로 numberOfSeats를 사용하여 최신 갱신 제안에 따라 갱신합니다.
  • SWITCH_TO_PAY_AS_YOU_GO: 연간 약정 요금제의 간격이 끝나면 연간 약정 요금제를 탄력 요금제로 변경합니다.
  • CANCEL: 연간 약정 요금제 기간이 종료되면 구독이 정지됩니다. 정지를 해제하는 방법을 알아보려면 관리 고객센터를 참고하세요.

성공적인 응답은 HTTP 201 상태 코드와 업데이트된 정기 결제 갱신 설정을 반환합니다.

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

무료 체험 구독에서 유료 서비스 시작

평가판 구독에 이미 요금제가 설정되어 있는 경우 30일 무료 평가판 구독을 유료 서비스 구독으로 즉시 이동하려면 다음 POST HTTP 요청을 사용하세요. 

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

다음을 바꿉니다.

  • CUSTOMER_ID: 고객의 기본 도메인 이름 또는 고객의 고유 식별자입니다.
  • SUBSCRIPTION_ID: 각 고객에게 고유한 정기 결제 식별자입니다. 모든 리셀러 구독 검색 메서드를 사용하여 이 값을 검색할 수 있습니다.

다음 예시에서는 C0123456이 customerId이고 subscriptionId 값이 123입니다.

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

이 작업에는 요청 본문에 매개변수가 없습니다.

성공한 응답은 HTTP 201 상태 코드와 업데이트된 구독 설정을 반환합니다.

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

구독 업그레이드 또는 다운그레이드

기간 중간에 연간 요금제를 다운그레이드할 수 없으며 갱신 설정을 사용하여 다운그레이드를 예약할 수도 없습니다. 갱신 시 FLEXIBLE로 전환한 다음 갱신 시간 후에 다운그레이드하도록 갱신 설정을 지정하는 것이 좋습니다.

구독을 업그레이드하거나 다운그레이드하려면 업그레이드 또는 다운그레이드하려는 skuId로 새 구독을 만드세요.

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

다음을 바꿉니다.

  • CUSTOMER_ID: 고객의 기본 도메인 이름 또는 고객의 고유 식별자입니다.

이 호출은 이전 구독을 종료하고 새 구독을 만듭니다.

제품 및 SKU 페이지에서 업그레이드 및 다운그레이드에 대해 자세히 알아보세요.