---
title: "Validate taxes on a billing schedule"
method: POST
path: "/billing-schedules/validate-taxes"
tags: ["Billing Schedules"]
---

# Validate taxes on a billing schedule

`POST /billing-schedules/validate-taxes`

Validate the tax strategy that will apply to the given billing schedule before it's created or updated.

## 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
    - `name` string — Optional name for the Phase
    - `externalContractRef` string — Free-text reference to the contract this phase rolls up to in an external system. Phases sharing a reference belong to the same contract; surrounding whitespace is trimmed, and matching is case-sensitive. On update, omitting this field or sending null clears any existing reference and has the phase roll up to the billing schedule itself.
    - `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` EmbeddableDiscountRequest[] — Discounts applicable to this phase
      - `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` MinimumRequest[] — Minimums applicable to this phase
      - `restrictToPrices` string[] — Price IDs to which this minimum applies
      - `amount` number, required — The minimum amount
    - `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.
      - `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' | 'HALF_YEARLY' | 'YEARLY', required
      - `billingFrequency` 'ONE_TIME' | 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY'
      - `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 `200`

OK

## Other responses

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

## Changes

- **2026-08-28** `e520d2f95b7b` — 7 breaking, 1 warning, 4 info
  - added the new required request property `phases/items/discounts/items/amount`
  - added the new required request property `phases/items/discounts/items/message`
  - added the new required request property `phases/items/discounts/items/separateLineItem`
  - added the new required request property `phases/items/discounts/items/type`
  - …8 more
- **2026-08-28** `d8d9b2c4fc1a` — 2 breaking, 9 warning, 1 info
  - the `phases/items/discounts/items/` request property type/format changed from `object`/`` to ``/``
  - the `phases/items/minimums/items/` request property type/format changed from `object`/`` to ``/``
  - removed the request property `phases/items/discounts/items/amount`
  - removed the request property `phases/items/discounts/items/message`
  - …8 more
- **2026-08-28** `05cc0975497f` — 7 breaking, 1 warning, 4 info
  - added the new required request property `phases/items/discounts/items/amount`
  - added the new required request property `phases/items/discounts/items/message`
  - added the new required request property `phases/items/discounts/items/separateLineItem`
  - added the new required request property `phases/items/discounts/items/type`
  - …8 more
- …earlier changes not shown

[Full history](https://skmtc.dev/sequencehq/apis/sequence/changes/billing-schedules/validate-taxes/post.md)

---

[API](https://skmtc.dev/sequencehq/apis/sequence.md) · [All operations](https://skmtc.dev/sequencehq/apis/sequence/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sequencehq/sequence/revisions/e520d2f95b7b/schema)