# Promotions

The platform currently supports two types of promotions: free trial promotions and introductory pricing promotions. Promotions can be applied when creating or provisioning a subscription.

## Introductory Pricing Promotions

Introductory pricing promotions decrease the initial subscription costs for a set number of recurrences by a discount amount. Multiple introductory pricing specifications can be defined in a single promotion. For example, a single promotion, can specify

- for the first billing cycle, decrease the subscription cost by 5 dollars
- for the next two billing cycles, decrease the subscription cost by 2 dollars

The recurrence counts of the introductory pricing promotions are specified in a promotion's [introductoryPricingDetails](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.promotions#IntroductoryPricingDetails)

Below is an example of a subscription with an introductory pricing promotion.

    {
      "lineItems": [
        {
          "product": "partners/test_partner1/products/RSG1PD.6782-1424"
        }
        // line-item level introductory pricing promotion.
       "lineItemPromotionSpecs": [
          {
            "promotion": "partners/test_partner1/promotions/RSG1PM.8865-1000"
          }
        ],
      ],
      "serviceLocation": {
        "regionCode": "US"
      },
      "partnerUserToken": "partner-user123"
    }

## Free Trial Promotions

A free trial promotion provides a service free of charge for a period of time, which effectively delays the initial charge while providing the user access to the service(s).

### Subscription level free trial

A subscription-level free trial defers the initial billing cycle of the entire subscription if specified.

Partners can only apply one free trial promotion to a given subscription in `promotionSpecs[]`.

We will use the duration specified in a promotion's [freeTrialDuration](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.promotions) after exercising the eligibility checks.

Below is an example of a subscription with a free trial promotion.

    {
      "lineItems": [
        {
          "product": "partners/test_partner1/products/RSG1PD.6782-1424"
        }
      ],
      // top-level free trial promotion applies to all line items.
      "promotionSpecs": [
        {
          "promotion": "partners/test_partner1/promotions/RSG1PM.8865-1018"
        }
      ],
      "serviceLocation": {
        "regionCode": "US"
      },
      "partnerUserToken": "partner-user123"
    }

### Line item level free trial \[feature not enabled\]

A line-item-level free trial applies to the current line item only. The trial starts immediately at the time of the request regardless of the top-level free trial. It will incur a prorated charge at the end of the trial.

    {
      "lineItems": [
        {
          "product": "partners/test_partner1/products/RSG1PD.6782-1424"
          // line-item-level free trial promotion applies this line item
          // specifically. Subscription level free trial has no effect on this line
          // item.
          "lineItemPromotionSpecs": [
            {
              "promotion": "partners/test_partner1/promotions/RSG1PM.8865-1018"
            }
          ],
        }
      ],
      "serviceLocation": {
        "regionCode": "US"
      },
      "partnerUserToken": "partner-user123"
    }