Outbound authorizations (optional)

Stay organized with collections Save and categorize content based on your preferences.

We provide a set of optional outbound authorization APIs for partners to approve of a new subscription signup or an add-on (a.k.a new line item) purchase. Partners may need to implement this integration for certain Google products that support in-app purchases, such as Youtube TV.

This section provides guidance on how to implement integration for partner-side authorizations.

Authorization flows

New subscription sign up

Partners will first receive authorizeSignup to authorize subscription creation, and then receive another authorizeCharge to authorize the charge. Google will delay authorizeCharge until the end of the free trial if applicable.

See the sample requests and responses below:

POST https://{partner_endpoint}/v1/partners/partner1/subscriptions:authorizeSignup HTTP/1.1

Accept: application/json
Content-Type: application/json

{
    "requestId": "c153c03c474d2c44",
    "subscription": {
        "partnerUserToken": "user1",
        "lineItems": [
            {
                "product": "partners/partner1/products/RSG1PD.1234-5678-9101",
                "description": "base subscription",
                "amount": {
                    "currency": "USD",
                    "amountInMicros": 10000000
                },
                "state": "LINE_ITEM_STATE_NEW"
            }
        ]
    }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "subscriptionId": "partnerAssignedSubscriptionId",
    "authorizationResult": "AUTHORIZATION_RESULT_AUTHORIZED"
}


POST https://{partner_endpoint}/v1/partners/partner1/purchaseorders:authorizeCharge HTTP/1.1

Accept: application/json
Content-Type: application/json

{
  "requestId": "a987dsa98",
  "purchaseOrder": {
    "partnerUserToken": "user1",
    "lineItems": [
      {
        "product": "partners/partner1/products/RSG1PD.1234-5678-9101",
        "description": "base subscription",
        "amount": {
          "currency": "USD",
          "amountInMicros": 10000000
        },
        "servicePeriod": {
          "startTime": "2022-04-01T00:00:00Z",
          "endTime": "2022-05-01T00:00:00Z"
        }
      }
    ]
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "purchaseOrderId": "partnerAssignedPurchaseOrderId",
    "authorizationResult": "AUTHORIZATION_RESULT_AUTHORIZED"
}

The partner must approve both requests for Google to fulfill the new sign up. If the partner declines authorizeCharge, the newly created subscription will be canceled.

In-app subscription add-on purchase

Partners will first receive authorizeAddon to authorize adding new line items to an existing subscription, and then receive another authorizeCharge to authorize the charge, potentially with a prorated amount. Google will delay authorizeCharge until the end of the free trial if the line items uses one.

The partner must approve both requests for Google to fulfill the add-on purchase. If the partner declines authorizeCharge, the newly added subscription line item will be deactivated.

See the sample requests and responses below:

POST https://{partner_endpoint}/v1/partners/partner1/subscriptions/sub1:authorizeAddon HTTP/1.1

Accept: application/json
Content-Type: application/json

{
    "requestId": "c153c03c474d2c44",
    "subscription": {
        "name": "partners/partner1/subscriptions/sub1",
        "partnerUserToken": "user1",
        "lineItems": [
            {
                "product": "partners/partner1/products/RSG1PD.1234-5678-9101",
                "description": "a base subscription",
                "amount": {
                    "currency": "USD",
                    "amountInMicros": 20000000
                },
                "state": "LINE_ITEM_STATE_ACTIVE"
            }
        ]
    },
    "newLineItems": [
        {
          "product": "partners/partner1/products/product_addon1",
          "description": "addon subscription",
          "amount": {
            "currency": "USD",
            "amountInMicros":1000000
          },
          "state": "LINE_ITEM_STATE_NEW",
          "recurrenceType": "LINE_ITEM_RECURRENCE_TYPE_PERIODIC"
        }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "authorizationResult": "AUTHORIZATION_RESULT_AUTHORIZED"
}



POST https://{partner_endpoint}/v1/partners/partner1/purchaseorders:authorizeCharge HTTP/1.1

Accept: application/json
Content-Type: application/json
{
  "requestId": "9876",
  "purchaseOrder": {
    "partnerUserToken": "test-token",
    "lineItems": [
      {
        "product": "partners/partner1/products/product_addon1",
        "description": "addon subscription",
        "amount": {
          "currency": "USD",
          "amountInMicros": 670000
        },
        "servicePeriod": {
          "startTime": "2022-04-11T00:00:00Z",
          "endTime": "2022-05-01T00:00:00Z"
        }
      }
    ]
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "purchaseOrderId": "partnerAssignedPurchaseOrderId",
    "authorizationResult": "AUTHORIZATION_RESULT_AUTHORIZED"
}

Monthly renewal

Partners will receive a single authorizeCharge call if they are configured to authorize Google initiated actions. Upon approval, the Google will charge the transaction and extend the service for the end user for another cycle. If the partner declines authorizeCharge, the existing subscription will be canceled.

Events that can trigger outbound authorization

Entity Event Partner Initiated Google Initiated API
Subscription New sign up Create/Provision API In-app new signup authorizeSignup
Subscription Add-on purchase N/A In-app add-on purchase authorizeAddon
PurchaseOrder Charge N/A New sign up, monthly renewal, in-app one-time purchase authorizeCharge

Configurations

Partners must finalize the following configurations with Google's partners team to enable the outbound authorization integration.

  • If or not enable outbound authorization for Google initiated actions.
  • If or not enable outbound authorization for partner initiated actions.
  • The corresponding endpoint that implements each authorization API spec.