> ## Documentation Index
> Fetch the complete documentation index at: https://docs-int.wingback.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variable Invoicing Schedules

export const IntRedir = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    setTimeout(() => {
      const currentUrl = new URL(window.location.href);
      if (currentUrl.hostname === 'docs-int.wingback.com') {
        currentUrl.hostname = 'docs.wingback.com';
        window.location.replace(currentUrl.toString());
      }
    }, 1);
    return <></>;
  }
};

<IntRedir />

Variable invoicing schedules allow you to send periodic invoices on a different cycle than the billing cycle of the contract/plan.

<Note>Custom schedule for invoices can be configured globally, or specified on signing the contract. If custom schedule is not specified on contract creation/signing, it will be copied from your global settings into the contract automatically. The invoice schedule defines when the invoice will be issued, and is independent of the billing cycle set for that plan (e.g. yearly). If multiple charges have occured (for example through mid-cycle upgrades), they will be rolled up into one (“multi-contract”/multi-charge) invoice.</Note>

<Note>Variable Invoicing Schedules can currently only be configured via API (Coming to the Interface soon).</Note>

<Warning>Currently it is <u>not possible</u> to change the invoicing schedule for a contract once it was created/signed (including future upgrades of that contract) - you would need to cancel the existing contract and sign a new one.</Warning>

## Configuring Variable Invoicing Schedules

<Steps>
  <Step title="1. Configure the global invoicing schedule (optional)">
    see [API: Global Invoicing Preferences](/dev/api-reference/invoice/post_c_preferences_invoicing)

    This step is optional - if you have a mix of self-serve and negotiated contracts, we recommend setting the invoicing schedule on a per plan or per contract level (Step 3)

    ```json POST https://api.app.wingback.com/v1/c/preferences/invoicing theme={null}
    {
        "invoice_trigger": {
            "periodic": {
            "cycle_count": 1,
            "cycle": "quarter",
            "cycle_start_offset": 1
            }
        }
    }
    ```

    *In this example invoices will be sent every 1 quarter, on the first day of the quarter. You can configure it to be every nth day (`cycle_start_offset`) of the month, quarter or year (`cycle`). If you do not set `cycle_start_offset` the invoice cycle will be aligned with the start of the contract or the end of the free trial (if any). `cycle_count` configures periodicity - so 1 means every quarter, 2 means every 2 quarters and so on.*
  </Step>

  <Step title="2. Create a customer (if not already created previously)">
    see [API: Create New Customer](/dev/api-reference/customer/post_c_customer)
  </Step>

  <Step title="3. Create/Sign a (new) contract for the customer">
    see [API: Subscribe Customer to a Plan](/dev/api-reference/contract/post_c_contract)

    If you haven't configured a global schedule (or want to overwrite it), you can specify a **custom invoicing schedule** when subscribing a customer to a <u>new</u> plan. In this example, the plan has unit-based pricing, so we need to specify the purchased unit count:

    ```json POST https://api.app.wingback.com/v1/c/contract theme={null}
    {
        "currency": "eur",
        "customer": "{customer_id}",
        "cycle": "month",
        "plan": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
        "invoice_trigger": {
            "periodic": {
                "cycle_count": 2,
                "cycle": "month"
            }
        },
        "feature_configuration": {
            "{feature_slug}": {
            "unit_count": 5
            }
        }
    }
    ```

    *In this example, invoices are generated every two months.*
  </Step>
</Steps>

## Working with Variable Invoicing Schedules

### Mid-Cycle Upgrades

Once the contract is `active`, the customers [entitlements](/dev/api-reference/entitlement/get_c_entitlement_customerid_access) will reflect the contracted unit count.

You can perform a **mid-cylce upgrade** of the contract to change the purchased unit count at any point:

```json POST https://api.app.wingback.com/v1/c/contract/upgrade theme={null}
{
  "upgrade_strategy": "change_unit_count",
  "unit_count_configuration": {
    "{feature_slug}": 5
  },
  "activation": {
    "type": "date",
    "upgrade_date": "{date_of_the_upgrade}"
  }
}
```

*This will perform a mid-cycle upgrade, prorating the amounts already paid in the current billing cycle and create new charges for them. The invoicing schedule set during the initial signing of the contract will carry over into the new period.*

Once the next invoice scheduling period has passed, a rolled-up invoice will be generated, containing all charges that occurred in this invoice schedule cycle.

### Manually Trigger Invoices

see [API: Manually Trigger Invoice Generation](/dev/api-reference/invoice/post_c_invoice)

*Optionally*, If you want to issue an invoice outside the invoicing schedule cycle, you can manually trigger an invoice creation that will contain all new charges up to this point.

```json POST https://api.app.wingback.com/v1/c/invoice theme={null}
{
  "contract_id": "Cont_c78b7e80-154c-4bf2-9b2a-5b4a58e005a2",
  "customer_id": "Cust_e23130bc-13e0-4b9a-876a-6d260c817677"
} 
```