# Scheduling temporary revenue shares

Schedule a temporary revenue share for a creator group through the Creator Code API or the Nexus Dashboard.

Temporary revenue shares may be scheduled through the Creator Code API, or through your [Nexus Dashboard](https://nexus.gg/publisher/dashboard). During the time frame specified, the revenue share of the schedule will be used instead of the default revenue share for the creator group. Only one scheduled revenue share may be active at a time.

See the [scheduled revenue share reference](/api/operations/getscheduledrevshares/) for full details.

<Aside type="note">
All scheduled revenue share routes use your private API key.
</Aside>

<Aside type="note">
Your default Creator Group will be used unless a `groupId` query parameter is specified on each request.
</Aside>

## Adding a new scheduled revenue share

To schedule a temporary revenue share, POST to the following route with the revenue share percent, start date, and end date.

<ApiMethod method="POST" path="/manage/scheduled-rev-shares" />
<LinkCard title="View full reference" description="Parameters, responses, and status codes." href="/api/operations/createscheduledrevshare/" />

<Aside type="caution">
Start and End dates should be in UTC when using the Attribution API. Rev Shares scheduled through the Nexus Dashboard will be automatically converted to UTC from your local time.
</Aside>

Here's how you call that with `curl`.

```bash
curl -X 'POST' \
  'https://api.nexus.gg/v1/manage/scheduled-rev-shares' \
  -H 'accept: application/json' \
  -H 'X-SHARED-SECRET: nexus_sk_your_key_here' \
  -d '{
  "revShare": 20,
  "startDate": "2023-06-21T15:00:00.000Z",
  "endDate": "2023-06-23T15:00:00.000Z",
  "tierRevenueShares": [
    {
      "tierId": "PGUeDx1h9dB5_-Or-CtJO",
      "revShare": 25
    },
    {
      "tierId": "R4hScVHFLHLtL63UyzCOA",
      "revShare": 30
    }
  ]
  }'
```

The status should be `200 OK` with a JSON response body that looks something like this:

```json
{
  "id": "dc5_phCpboQM8bnJel9Nj",
  "revShare": 20,
  "startDate": "2023-06-21T15:00:00.000Z",
  "endDate": "2023-06-23T15:00:00.000Z",
  "groupId": "AJ9OPrEFt4AAVJcA",
  "groupName": "My Super Cool Game 2",
  "tierRevenueShares": [
    {
      "tierId": "PGUeDx1h9dB5_-Or-CtJO",
      "revShare": 25,
      "tierName": "Bronze"
    },
    {
      "tierId": "R4hScVHFLHLtL63UyzCOA",
      "revShare": 30,
      "tierName": "Silver"
    }
  ]
}
```

### Creator Group Tiers with scheduled revenue shares

When creating a scheduled revenue share, you may optionally provide Creator Group Tier specific `revShare` values by including the `tierRevenueShares` property in the request body.

```json
"tierRevenueShares": [
    {
      "tierId": "PGUeDx1h9dB5_-Or-CtJO",
      "revShare": 25,
      "tierName": "Bronze"
    },
    {
      "tierId": "R4hScVHFLHLtL63UyzCOA",
      "revShare": 30,
      "tierName": "Silver"
    }
  ]
```

Any creator that is part of a tier will use the tier specific `revShare` of an active scheduled revenue share. If tier specific revShare was provided, then the creator's standard tier revenue share will be used. **It will not default to the base revShare of the scheduled revenue share**.

For example, if a creator is in Silver tier during the scheduled revenue share described above, they will receive a 25% revenue share. However, if you have a Gold tier that normally receives 18% revenue share, the creators in that tier will still receive 18% while this scheduled revenue share is active because the Gold tier did not have a `revShare` specified.

The base `revShare` may also be left empty when scheduling revenue shares, allowing you to schedule a revenue share change for only specific tiers.

```json
{
  "id": "dc5_phCpboQM8bnJel9Nj",
  "startDate": "2023-06-21T15:00:00.000Z",
  "endDate": "2023-06-23T15:00:00.000Z",
  "groupId": "AJ9OPrEFt4AAVJcA",
  "groupName": "My Super Cool Game 2",
  "tierRevenueShares": [
    {
      "tierId": "R4hScVHFLHLtL63UyzCOA",
      "revShare": 20,
      "tierName": "Silver"
    }
  ]
}
```

In the example above, only the silver tier would receive a different revenue share while this schedule was active.

## List scheduled revenue shares for a group

<ApiMethod method="GET" path="/manage/scheduled-rev-shares" />
<LinkCard title="View full reference" description="Parameters, responses, and status codes." href="/api/operations/getscheduledrevshares/" />

Here's how you call that with `curl`.

```bash
curl -X 'GET' \
  'https://api.nexus.gg/v1/manage/scheduled-rev-shares' \
  -H 'accept: application/json' \
  -H 'X-SHARED-SECRET: nexus_sk_your_key_here'
```

The status should be `200 OK` with a JSON response body that looks something like this:

```json
{
  "groupId": "AJ9OPrEFt4AAVJcA",
  "groupName": "My Super Cool Game 2",
  "currentPage": 1,
  "currentPageSize": 100,
  "totalCount": 3,
  "scheduledRevShares": [
    {
      "id": "dpk_rk_kn6Ixz3qkdxs",
      "revShare": 15,
      "startDate": "2023-06-23T15:00:00.000Z",
      "endDate": "2023-07-23T15:00:00.000Z",
      "groupId": "AJ9OPrEFt4AAVJcA",
      "groupName": "My Super Cool Game 2",
      "status": "Scheduled",
      "tierRevenueShares": [
        {
          "tierId": "PGUeDx1h9dB5_-Or-CtJO",
          "revShare": 20,
          "tierName": "Bronze"
        },
        {
          "tierId": "R4hScVHFLHLtL63UyzCOA",
          "revShare": 25,
          "tierName": "Silver"
        }
      ]
    },
    {
      "id": "dc5_phCpboQM8bnJel9Nj",
      "revShare": 20,
      "startDate": "2023-06-21T15:00:00.000Z",
      "endDate": "2023-06-23T15:00:00.000Z",
      "groupId": "AJ9OPrEFt4AAVJcA",
      "groupName": "My Super Cool Game 2",
      "status": "Active",
      "tierRevenueShares": [
        {
          "tierId": "PGUeDx1h9dB5_-Or-CtJO",
          "revShare": 25,
          "tierName": "Bronze"
        },
        {
          "tierId": "R4hScVHFLHLtL63UyzCOA",
          "revShare": 30,
          "tierName": "Silver"
        }
      ]
    },
    {
      "id": "fld5591dldaj340sa",
      "revShare": 20,
      "startDate": "2022-03-01T00:00:00.000Z",
      "endDate": "2022-04-01T00:00:00.000Z",
      "groupId": "AJ9OPrEFt4AAVJcA",
      "groupName": "My Super Cool Game 2",
      "status": "Ended",
      "tierRevenueShares": [
        {
          "tierId": "PGUeDx1h9dB5_-Or-CtJO",
          "revShare": 25,
          "tierName": "Bronze"
        },
        {
          "tierId": "R4hScVHFLHLtL63UyzCOA",
          "revShare": 30,
          "tierName": "Silver"
        }
      ]
    }
  ]
}
```