---
title: "Create Billing Schedule"
method: POST
path: "/billing-schedules"
tags: ["Billing Schedules"]
---

# Create Billing Schedule

`POST /billing-schedules`

Create a new [Billing Schedule](/billing/create-billing-schedules).

## Headers

- `Authorization` string, required
- `sequence-version` '2024-07-30'

## Request body

- CreateBillingScheduleRequest
  - `customerId` string, required — Customer ID
  - `startDate` string, required — Start date
  - `endDate` string — End date. A null end date denotes an open-ended schedule.
  - `recurrenceDayOfMonth` integer — Recurrence day of month
  - `taxRates` ProductTaxRateRepresentation[], required — Tax Rate for each Product
    - `priceId` string, required — ID of the Price
    - `taxRateId` string, required — ID of the Tax Rate
  - `autoIssueInvoices` boolean, required — Auto-issue invoices for this billing schedule
  - `purchaseOrderNumber` string — Optional purchase order number to be added to invoices
  - `reference` string — Optional reference to be added to invoices
  - `label` string — Optional label
  - `paymentProvider` 'STRIPE' | 'GOCARDLESS' | 'NONE'
  - `isDraft` boolean, required — Create in draft status
  - `rollUpBilling` boolean, required — Toggles Roll-up billing
  - `phases` PhaseRequest[], required — Phases
    - `priceIds` string[], required — The price IDs included in this phase
    - `startDate` string, required — Phase start date
    - `endDate` string — Phase end date. A null end date denotes an open-ended phase. Only the last phase can be open-ended.
    - `discounts` unknown[] — Discounts applicable to this phase
      - unknown
    - `minimums` unknown[] — Minimums applicable to this phase
      - unknown
    - `creditGrants` EmbeddableCreditGrantRequest[] — Credit grants applicable to this phase. Omit this field on every phase to leave the schedule's existing grants untouched. Once any phase provides it, the grants across all phases are the schedule's full grant spec: grants without an ID are created, grants re-sent with their ID are kept, and grants left out are removed. Grants cannot be updated through this request, and a grant that has already been drawn down cannot be removed this way — delete it through the credit grant endpoint instead.
      - `id` string — ID of an existing credit grant on this billing schedule. Omit to create a new grant. When present, the grant is kept as-is — credit grants cannot be updated through a billing schedule edit.
      - `name` string, required — Name of the credit grant.
      - `creditUnitType` 'CURRENCY' | 'METRIC', required
      - `currency` 'AED' | 'ARS' | 'AUD' | 'BRL' | 'BGN' | 'CAD' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'EGP' | 'EUR' | 'GBP' | 'HKD' | 'ILS' | 'INR' | 'ISK' | 'JPY' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PLN' | 'SAR' | 'SEK' | 'SGD' | 'THB' | 'USD' | 'UYU' | 'ZAR'
      - `amount` number, required — Amount of units granted.
      - `costOfCredit` number — Cost of credit grant.
      - `taxRateId` string — Tax rate ID for the credit grant.
      - `grantRefreshFrequency` 'NONE' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY', required
      - `rolloverMode` 'NONE' | 'ON_GRANT_REFRESH' | 'ON_GRANT_REFRESH_AND_PHASE', required
      - `restrictToPrices` string[] — Price IDs the grant is consumed against. Omit or leave empty to apply to every price in the phase.
    - `listPriceIds` string[] — IDs of list prices from which to create prices for this phase
    - `recurrencePreference` 'CONTINUE_FROM_PREVIOUS_PHASE' | 'RESET'
    - `phasePriceMetadata` PhasePriceMetadata[] — Additional metadata for the relationship between this phase and each price
      - `priceId` string, required
      - `arrCalculation` 'INCLUDE' | 'EXCLUDE', required
    - `phaseListPriceMetadata` PhaseListPriceMetadata[] — Additional metadata for the relationship between this phase and each list price
      - `listPriceId` string, required
      - `arrCalculation` 'INCLUDE' | 'EXCLUDE', required
  - `attachmentAssetIds` string[] — IDs of assets that are attached to this schedule
  - `autoCharge` boolean — Automatically collect payments if payment details are available
  - `defaultDueDateDays` integer — Default number of days between invoice issue date and due date. Overrides any invoice level set default due date
  - `memo` string — Billing schedule memo. Overrides any invoice level set memo
  - `customFields` object — Custom key-value fields for this billing schedule

## Response `201`

Created

- BillingScheduleResponse
  - `id` string, required — Billing Schedule ID
  - `customerId` string, required — Customer ID
  - `status` 'DRAFT' | 'PENDING' | 'ACTIVE' | 'SUSPENDED' | 'CANCELLED' | 'COMPLETED', required
  - `startDate` string, required — Start date
  - `endDate` string — End date
  - `taxRates` ProductTaxRateRepresentation[] — Tax Rate for each Product
    - `priceId` string, required — ID of the Price
    - `taxRateId` string, required — ID of the Tax Rate
  - `firstBillingDate` string — First billing date
  - `autoIssueInvoices` boolean, required — If true, invoices will be automatically sent for this billing schedule
  - `purchaseOrderNumber` string — Optional purchase order number to be added to invoices
  - `reference` string — Optional reference to be added to invoices
  - `label` string — Optional label
  - `recurrenceDayOfMonth` integer — The day of the month on which billing recurs
  - `prices` PriceResponse[], required — Prices
    - `id` string, required — Unique Price ID, generated by Sequence on creation.
    - `productId` string, required — The ID of the Product that this Price is associated with.
    - `name` string, required — A short form description of the price, which appears as the title of line items on invoices.
    - `currency` 'AED' | 'ARS' | 'AUD' | 'BRL' | 'BGN' | 'CAD' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'EGP' | 'EUR' | 'GBP' | 'HKD' | 'ILS' | 'INR' | 'ISK' | 'JPY' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PLN' | 'SAR' | 'SEK' | 'SGD' | 'THB' | 'USD' | 'UYU' | 'ZAR', required
    - `structure` union, required
      - GraduatedPricingStructure — The pricing structure for this price. This can be a simple fixed price, or a more complex structure that varies based on usage.
        - `tiers` GraduatedUsageTier[], required — A list of contiguous pricing tiers
          - `upperBound` string — The upper bound of usage for this tier. Set to null to if this is a final tier and is unbounded. The lower bound is set by the previous tier or 0 if it's the first one.
          - `price` string, required — The rate to apply to usage for this product in this tier. In the case of percentage pricing where `isPricePercentage` is set to `true`, a value of 1 represents 100%.
          - `fee` string — The nominal fee associated with usage at this tier
          - `isPricePercentage` boolean, required — Indicate whether the price attribute is to be considered as a percentage or an absolute value.
        - `usageMetricId` string, required — The usage metric associated to this pricing structure
        - `usageCalculationMode` 'BILLING_PERIOD' | 'CUMULATIVE' | 'PERIODIC', required
        - `pricingType` 'GRADUATED', required
      - VolumePricingStructure — The pricing structure for this price. This can be a simple fixed price, or a more complex structure that varies based on usage.
        - `tiers` VolumeUsageTier[], required — A list of contiguous pricing tiers
          - `upperBound` string — The upper bound of usage for this tier. Set to null to if this is a final tier and is unbounded. The lower bound is set by the previous tier or 0 if it's the first one.
          - `price` string, required — The rate to apply to usage for this product in this tier. In the case of percentage pricing where `isPricePercentage` is set to `true`, a value of 1 represents 100%.
          - `fee` string — The nominal fee associated with usage at this tier
          - `isPricePercentage` boolean, required — Indicate whether the price attribute is to be considered as a percentage or an absolute value.
          - `maxPrice` string — Maximum Price to Charge for each Unit if Price is Percentage Based
          - `minPrice` string — Minimum Price to Charge for each Unit if Price is Percentage Based
        - `usageMetricId` string, required — The usage metric associated to this tier
        - `pricingType` 'VOLUME', required
      - SeatBasedPricingStructure — The pricing structure for this price. This can be a simple fixed price, or a more complex structure that varies based on usage.
        - `seatMetricId` string, required — Seat metric associated to this pricing structure
        - `pricePerSeat` string, required — Price charged per seat per full billing period
        - `prorationStrategy` 'USE_MAXIMUM' | 'PRORATE_INCREMENTS' | 'PRORATE_ALL_CHANGES', required
        - `contractedMinimumSeats` integer, required — The number of contractually agreed minimum seats
        - `overagesBillingFrequency` 'NONE' | 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY'
        - `tiers` SeatUsageTier[], required — A list of contiguous pricing tiers
          - `upperBound` string — The upper bound of usage for this tier. Set to null to if this is a final tier and is unbounded. The lower bound is set by the previous tier or 0 if it's the first one.
          - `price` string, required — The rate to apply to usage for this product in this tier. In the case of percentage pricing where `isPricePercentage` is set to `true`, a value of 1 represents 100%.
          - `fee` string — The nominal fee associated with usage at this tier
        - `prorateFlatFees` boolean — If set any flat fees will be pro-rated if the invoice service period length does not match the billing frequency
        - `pricingType` 'SEAT_BASED', required
      - PackagePricingStructure — The pricing structure for this price. This can be a simple fixed price, or a more complex structure that varies based on usage.
        - `packageSize` string, required — The amount of usage allowed for the price in this structure
        - `pricePerPackage` string, required — The price charged for each package
        - `usageMetricId` string, required — The usage metric associated to this tier
        - `pricingType` 'PACKAGE', required
      - LinearPricingStructure — The pricing structure for this price. This can be a simple fixed price, or a more complex structure that varies based on usage.
        - `pricePerUnit` string, required — The per unit rate to apply to usage for this product. In the case of percentage pricing where `isPricePercentage` is set to `true`, a value of 1 represents 100%.
        - `usageMetricId` string, required — Usage metric associated to this pricing structure
        - `isPricePercentage` boolean, required — Indicate whether the price attribute is to be considered as a percentage or an absolute value.
        - `pricingType` 'LINEAR', required
      - FixedPricingStructure — The pricing structure for this price. This can be a simple fixed price, or a more complex structure that varies based on usage.
        - `price` string, required — A fixed amount that is charged once every billing period.
        - `pricingType` 'FIXED', required
      - OneTimePricingStructure — The pricing structure for this price. This can be a simple fixed price, or a more complex structure that varies based on usage.
        - `price` string, required — A fixed amount that is charged once.
        - `pricingType` 'ONE_TIME', required
    - `billingFrequency` 'ON_DEMAND' | 'ONE_TIME' | 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY' | 'PER_EVENT', required
    - `billingType` 'IN_ARREARS' | 'IN_ADVANCE', required
    - `createdAt` string, required — Time at which the Price was initially created, in ISO 8601 format.
    - `updatedAt` string — Time at which the Price was last updated, in ISO 8601 format.
    - `integrationIds` IntegrationId1[], required — Alternate IDs for this Price in third-party integration systems
      - `service` 'Amazon_Redshift' | 'GoCardless' | 'Google_BigQuery' | 'Google_Sheets' | 'HubSpot' | 'NetSuite' | 'QuickBooks_Online' | 'Salesforce' | 'Slack' | 'Snowflake' | 'Stripe' | 'Xero' | 'Avalara' | 'Anrok' | 'Attio' | 'Numeral' | 'Rillet' | 'Sphere', required
      - `id` string, required
      - `isPending` boolean, required
    - `customMetricParameters` PriceParameter[], required — Specific parameters to influence usage calculation for this Price, and are only required when using custom metric. Please speak to your Sequence contacts for further information prior to usage.
      - `parameterId` string, required — Custom metric parameter ID
      - `value` string, required — Parameter value
    - `listPriceId` string — The list price ID, if this price variant was created from a list price
    - `usageCalculationPeriod` UsageCalculationPeriod — The period over which usage is aggregated.
      - `frequency` 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY', required
      - `interval` integer, required — Interval determines the time period over which usage is aggregated. For example, if the frequency is MONTHLY and the interval is 3, the usage is aggregated over 3 months before starting at 0 again.
    - `status` 'DRAFT' | 'ACTIVE', required
  - `createdAt` string, required — Time at which the schedule was initially created, in ISO 8601 format.
  - `updatedAt` string, required — Time at which the schedule was last updated, in ISO 8601 format.
  - `lastInvoiceId` string — ID of the last invoice (if there has been one)
  - `phases` Phase[], required — Phases
    - `id` string, required — Phase ID
    - `name` string — Name
    - `createdAt` string, required — Created at
    - `billingScheduleId` string, required — Billing Schedule ID
    - `priceIds` string[], required — Price IDs
    - `startDate` string, required — Start Date
    - `endDate` string — End date
    - `discounts` EmbeddableDiscount[], required — Discounts in Phase
      - `id` string, required — Discount ID
      - `restrictToPrices` string[] — Price IDs to which this discount applies
      - `type` 'PERCENTAGE' | 'NOMINAL', required
      - `amount` number, required — The discount amount
      - `message` string, required — The message to show on an invoice
      - `separateLineItem` boolean, required — If true the discount will show as a separate line item on an invoice
      - `seatDiscountType` 'INCLUDED_SEATS_ONLY' | 'OVERAGE_SEATS_ONLY' | 'ALL_SEATS'
    - `minimums` Minimum[], required
      - `id` string, required — Minimum ID
      - `sequenceAccountId` string, required — Sequence Account ID
      - `billingScheduleId` string, required — Billing Schedule ID
      - `phaseId` string, required — Phase ID
      - `amount` number, required — Minimum amount
      - `restrictToPrices` string[], required — Price IDs the minimum is restricted to
      - `createdAt` string, required — Created at
      - `updatedAt` string, required — Updated at
    - `creditGrants` EmbeddableCreditGrant[], required — Credit grants in Phase
      - `id` string, required — Credit grant ID.
      - `name` string, required — Name of the credit grant.
      - `creditUnitType` 'CURRENCY' | 'METRIC', required
      - `currency` 'AED' | 'ARS' | 'AUD' | 'BRL' | 'BGN' | 'CAD' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'EGP' | 'EUR' | 'GBP' | 'HKD' | 'ILS' | 'INR' | 'ISK' | 'JPY' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PLN' | 'SAR' | 'SEK' | 'SGD' | 'THB' | 'USD' | 'UYU' | 'ZAR'
      - `amount` number, required — Amount of units granted.
      - `costOfCredit` number — Cost of credit grant.
      - `taxRateId` string — Tax rate ID for the credit grant.
      - `grantRefreshFrequency` 'NONE' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY', required
      - `rolloverMode` 'NONE' | 'ON_GRANT_REFRESH' | 'ON_GRANT_REFRESH_AND_PHASE', required
      - `restrictToPrices` string[], required — Price IDs the grant is consumed against.
    - `recurrencePreference` 'CONTINUE_FROM_PREVIOUS_PHASE' | 'RESET', required
    - `phasePriceMetadata` PhasePriceMetadata[], required — Additional metadata for the relationship between this phase and each price
      - `priceId` string, required
      - `arrCalculation` 'INCLUDE' | 'EXCLUDE', required
  - `archivedAt` string — Time at which the schedule was archived, in ISO 8601 format.
  - `rollUpBilling` boolean, required — Roll up billing
  - `integrationIds` IntegrationId1[], required — External services which are linked to this customer
    - `service` 'Amazon_Redshift' | 'GoCardless' | 'Google_BigQuery' | 'Google_Sheets' | 'HubSpot' | 'NetSuite' | 'QuickBooks_Online' | 'Salesforce' | 'Slack' | 'Snowflake' | 'Stripe' | 'Xero' | 'Avalara' | 'Anrok' | 'Attio' | 'Numeral' | 'Rillet' | 'Sphere', required
    - `id` string, required
    - `isPending` boolean, required
  - `attachmentAssets` AssetResponse[], required — Assets attached to this billing schedule
    - `id` string, required — Unique ID
    - `createdBy` string, required — The Sequence user who created this asset
    - `type` 'IMAGE' | 'DOCUMENT' | 'BINARY', required
    - `format` 'JPEG' | 'JPG' | 'PNG' | 'PDF' | 'CSV' | 'TXT' | 'RTF' | 'MD' | 'XLS' | 'XLSX' | 'XLSM' | 'DOC' | 'DOCX' | 'ZIP' | 'ODT' | 'ODS', required
    - `fileName` string, required — Filename of the uploaded file
    - `fileSizeBytes` integer, required — Size of the uploaded file in bytes
    - `url` string, required — URL to download the asset
    - `createdAt` string, required — Creation timestamp. Formatted as an ISO 8601 timestamp.
  - `contractId` string — Optional ID of the contract used to create this billing schedule
  - `defaultDueDateDays` integer — Default number of days between invoice issue date and due date
  - `memo` string — Billing schedule memo
  - `customFields` object, required — Custom key-value fields for this billing schedule
  - `paymentProvider` 'STRIPE' | 'GOCARDLESS' | 'NONE'
  - `autoCharge` boolean — Whether invoices for this billing schedule are automatically charged. Only returned when paymentProvider is STRIPE

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `500` — Internal Server Error

---

[API](https://skmtc.net/sequencehq/apis/sequence.md) · [All operations](https://skmtc.net/sequencehq/apis/sequence/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sequencehq/sequence/versions/cae64b02699f/schema)