Archive Billing Schedule

API Reference

Latest Live API

Account
Billing
Collections
Customer
Invoices
Notifications
Product
Quote
Taxes
Usage

Version 2024-07-30

Account
Billing
- Prices
- Discounts
- Credits
- Billing Schedules
Collections
Customer
Invoices
Notifications
Product
Quote
Taxes
Usage

POST

billing-schedules

{billingScheduleId}

Headers

Authorization

string

required

Your API credentials. Eg. Basic {credentials}.

Sequence-Version

enum<string>

Use this header to select an API version

Available options:

2024-07-30

Path Parameters

billingScheduleId

string

required

Billing Schedule ID

Response

200

application/json

string

required

Billing Schedule ID

Example:

"b102e007-f5d7-4b1a-8a1d-9a51135ae73b"

customerId

string

required

Customer ID

Example:

"cca32597-b6b0-4499-9669-128aef8702e4"

status

enum<string>

required

Billing schedule status

Available options:

DRAFT,

PENDING,

ACTIVE,

SUSPENDED,

CANCELLED,

COMPLETED

Example:

"ACTIVE"

startDate

string

required

Start date

Example:

"2022-01-01"

autoIssueInvoices

boolean

required

If true, invoices will be automatically sent for this billing schedule

Example:

false

prices

object[]

required

Prices

prices.id

string

required

Unique Price ID, generated by Sequence on creation.

Example:

"bc61d4b8-e9d6-4f4a-9bcf-f5dae874c730"

prices.productId

string

required

The ID of the Product that this Price is associated with.

Example:

"d07037d5-3e31-4c3a-a360-e58555e2bf44"

prices.name

string

required

A short form description of the price, which appears as the title of line items on invoices.

Example:

"Demo Product"

prices.currency

enum<string>

required

The currency in which this price is denominated. This must be a valid ISO 4217 currency code, that is currently part of currencies supported by Sequence.

Available options:

ARS,

AUD,

BRL,

BGN,

CAD,

CHF,

CNY,

COP,

CZK,

DKK,

EUR,

GBP,

HKD,

ILS,

JPY,

KRW,

MXN,

NOK,

NZD,

PLN,

SEK,

SGD,

THB,

USD,

UYU,

ZAR

Example:

"GBP"

prices.structure

object

required

The pricing structure for this price. This can be a simple fixed price, or a more complex structure that varies based on usage.

prices.structure.tiers

object[]

required

A list of contiguous pricing tiers

Example:

[
  {
    "upperBound": "200",
    "price": "1.00",
    "fee": "50.00",
    "isPricePercentage": false
  },
  {
    "upperBound": "400",
    "price": "0.75",
    "fee": "25.00",
    "isPricePercentage": false
  },
  {
    "price": "0.50",
    "fee": "0.00",
    "isPricePercentage": false
  }
]

prices.structure.usageMetricId

string

required

The usage metric associated to this pricing structure

Example:

"04c62961-04ba-48e6-b985-758bb7d3e712"

prices.structure.usageCalculationMode

enum<string>

required

Indicates the scope of usage calculation

Available options:

BILLING_PERIOD,

CUMULATIVE,

PERIODIC

Example:

"BILLING_PERIOD"

prices.structure.pricingType

enum<string>

required

The type of pricing

Available options:

GRADUATED

Example:

"GRADUATED"

Example:

{
  "tiers": [
    {
      "upperBound": "200",
      "price": "1.00",
      "fee": "50.00",
      "isPricePercentage": false
    },
    {
      "upperBound": "400",
      "price": "0.75",
      "fee": "25.00",
      "isPricePercentage": false
    },
    {
      "price": "0.50",
      "fee": "0.00",
      "isPricePercentage": false
    }
  ],
  "usageMetricId": "04c62961-04ba-48e6-b985-758bb7d3e712",
  "usageCalculationMode": "BILLING_PERIOD",
  "pricingType": "GRADUATED"
}

prices.billingFrequency

enum<string>

required

The frequency with which this price is billed.

Available options:

ON_DEMAND,

ONE_TIME,

MONTHLY,

QUARTERLY,

HALF_YEARLY,

YEARLY

Example:

"MONTHLY"

prices.billingType

enum<string>

required

Indicate at which point of the billing period to generate the invoice for this price. This can be either in-arrears (after the period ends), or in-advnace (at the beginning of the period).

Available options:

IN_ARREARS,

IN_ADVANCE

Example:

"IN_ARREARS"

prices.createdAt

string

required

Time at which the Price was initially created, in ISO 8601 format.

Example:

"2022-06-28T16:47:00Z"

prices.integrationIds

object[]

required

Alternate IDs for this Price in third-party integration systems

Example:

[
  {
    "service": "Xero",
    "id": "123",
    "isPending": false
  }
]

prices.customMetricParameters

object[]

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.

Example:

[
  {
    "parameterId": "94703530-1293-479b-bd37-ccad42fd9c8b",
    "value": "10"
  }
]

prices.status

enum<string>

required

Price status:

DRAFT means the price has been extracted from a contract and has not yet been approved. It cannot be used while it is in DRAFT.
ACTIVE is the default state when a price is created via API or dashboard.

Available options:

DRAFT,

ACTIVE

Example:

"ACTIVE"

prices.updatedAt

string

Time at which the Price was last updated, in ISO 8601 format.

Example:

"2022-06-28T16:47:00Z"

prices.listPriceId

string

The list price ID, if this price variant was created from a list price

Example:

"b4d7e884-e007-4183-8355-4771865c5100"

prices.usageCalculationPeriod

object

The period over which usage is aggregated.

Example:

{ "frequency": "MONTHLY", "interval": 1 }

Example:

[
  {
    "id": "bc61d4b8-e9d6-4f4a-9bcf-f5dae874c730",
    "productId": "f409d651-c475-4142-aafd-a5d2bd74d4f9",
    "name": "Demo Product",
    "currency": "GBP",
    "structure": {
      "pricePerUnit": "0.25",
      "usageMetricId": "04c62961-04ba-48e6-b985-758bb7d3e712",
      "isPricePercentage": false,
      "pricingType": "LINEAR"
    },
    "billingFrequency": "MONTHLY",
    "billingType": "IN_ARREARS",
    "createdAt": "2022-06-28T16:47:00Z",
    "updatedAt": "2022-06-28T16:47:00Z",
    "integrationIds": [],
    "customMetricParameters": [
      {
        "parameterId": "94703530-1293-479b-bd37-ccad42fd9c8b",
        "value": "10"
      }
    ],
    "listPriceId": "b4d7e884-e007-4183-8355-4771865c5100",
    "status": "ACTIVE"
  }
]

createdAt

string

required

Time at which the schedule was initially created, in ISO 8601 format.

Example:

"2022-06-28T16:47:00Z"

updatedAt

string

required

Time at which the schedule was last updated, in ISO 8601 format.

Example:

"2022-06-28T16:47:00Z"

phases

object[]

required

Phases

phases.id

string

required

Phase ID

Example:

"6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"

phases.createdAt

string

required

Created at

Example:

"2022-06-28T16:47:00Z"

phases.billingScheduleId

string

required

Billing Schedule ID

Example:

"b102e007-f5d7-4b1a-8a1d-9a51135ae73b"

phases.priceIds

string[]

required

Price IDs

Example:

["6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"]

phases.startDate

string

required

Start Date

Example:

"2022-01-01"

phases.discounts

object[]

required

Discounts in Phase

phases.discounts.type

enum<string>

required

Whether the discount is a nominal or percentage amount

Available options:

PERCENTAGE,

NOMINAL

Example:

"PERCENTAGE"

phases.discounts.amount

number

required

The discount amount

Example:

0.08

phases.discounts.message

string

required

The message to show on an invoice

Example:

"8% Discount"

phases.discounts.separateLineItem

boolean

required

If true the discount will show as a separate line item on an invoice

Example:

true

phases.discounts.restrictToPrices

string[]

Price IDs to which this discount applies

Example:

["6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"]

phases.discounts.seatDiscountType

enum<string>

Determines how the discount is applied to any seat-based prices

Available options:

INCLUDED_SEATS_ONLY,

OVERAGE_SEATS_ONLY,

ALL_SEATS

Example:

"ALL_SEATS"

Example:

[
  {
    "restrictToPrices": ["6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"],
    "type": "PERCENTAGE",
    "amount": 0.15,
    "message": "15% Discount",
    "separateLineItem": true,
    "seatDiscountType": "ALL_SEATS"
  }
]

phases.minimums

object[]

required

phases.minimums.id

string

required

Minimum ID

Example:

"6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"

phases.minimums.sequenceAccountId

string

required

Sequence Account ID

Example:

"c4602d51-0fb4-4b48-b689-6ba28f540d1e"

phases.minimums.billingScheduleId

string

required

Billing Schedule ID

Example:

"b102e007-f5d7-4b1a-8a1d-9a51135ae73b"

phases.minimums.phaseId

string

required

Phase ID

Example:

"6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"

phases.minimums.amount

number

required

Minimum amount

Example:

100

phases.minimums.restrictToPrices

string[]

required

Price IDs the minimum is restricted to

Example:

["6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"]

phases.minimums.createdAt

string

required

Created at

Example:

"2022-06-28T16:47:00Z"

phases.minimums.updatedAt

string

required

Updated at

Example:

"2022-06-28T16:47:00Z"

Example:

[
  {
    "id": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
    "sequenceAccountId": "c4602d51-0fb4-4b48-b689-6ba28f540d1e",
    "billingScheduleId": "b102e007-f5d7-4b1a-8a1d-9a51135ae73b",
    "phaseId": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
    "amount": 100,
    "restrictToPrices": ["6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"],
    "createdAt": "2022-06-28T16:47:00Z",
    "updatedAt": "2022-06-28T16:47:00Z"
  }
]

phases.recurrencePreference

enum<string>

required

Available options:

CONTINUE_FROM_PREVIOUS_PHASE,

RESET

Example:

"CONTINUE_FROM_PREVIOUS_PHASE"

phases.phasePriceMetadata

object[]

required

Additional metadata for the relationship between this phase and each price

Example:

[
  {
    "priceId": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
    "arrCalculation": "INCLUDE"
  }
]

phases.name

string

Name

Example:

"Onboarding"

phases.endDate

string

End date

Example:

"2022-06-30"

Example:

[
  {
    "id": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
    "name": "Onboarding",
    "createdAt": "2022-06-28T16:47:00Z",
    "billingScheduleId": "b102e007-f5d7-4b1a-8a1d-9a51135ae73b",
    "priceIds": ["6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"],
    "startDate": "2022-01-01",
    "endDate": "2022-06-30",
    "discounts": [
      {
        "restrictToPrices": ["6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"],
        "type": "PERCENTAGE",
        "amount": 0.15,
        "message": "15% Discount",
        "separateLineItem": true,
        "seatDiscountType": "ALL_SEATS"
      }
    ],
    "minimums": [
      {
        "id": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
        "sequenceAccountId": "c4602d51-0fb4-4b48-b689-6ba28f540d1e",
        "billingScheduleId": "b102e007-f5d7-4b1a-8a1d-9a51135ae73b",
        "phaseId": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
        "amount": 100,
        "restrictToPrices": ["6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"],
        "createdAt": "2022-06-28T16:47:00Z",
        "updatedAt": "2022-06-28T16:47:00Z"
      }
    ],
    "recurrencePreference": "CONTINUE_FROM_PREVIOUS_PHASE",
    "phasePriceMetadata": [
      {
        "priceId": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
        "arrCalculation": "INCLUDE"
      }
    ]
  }
]

rollUpBilling

boolean

required

Roll up billing

Example:

false

integrationIds

object[]

required

External services which are linked to this customer

Example:

[
  {
    "service": "Salesforce",
    "id": "a0CQy00000Ipz5VMAR",
    "lastSynced": "2024-08-14T17:14:17Z",
    "url": "https://sequence-b-dev-ed.develop.my.salesforce.com/lightning/r/sequence__Billing_Schedule__c/a0CQy00000Ipz5VMAR/view",
    "isPending": false
  }
]

attachmentAssets

object[]

required

Assets attached to this billing schedule

Example:

[
  {
    "id": "e007e884-5100-4183-8355-4771865cb4dd",
    "createdBy": "94703530-1293-479b-bd37-ccad42fd9c8b",
    "type": "IMAGE",
    "format": "PNG",
    "fileName": "my-image.png",
    "fileSizeBytes": 12345,
    "url": "https://assets.sequencehq.com/018f9ad5-4192-76d7-aea5-d80a9018eded/images/e007e884-5100-4183-8355-4771865cb4dd.png",
    "createdAt": "2022-06-28T16:47:00Z"
  }
]

endDate

string

End date

Example:

"2022-12-01"

taxRates

object[]

Tax Rate for each Product

Example:

[
  {
    "priceId": "bc61d4b8-e9d6-4f4a-9bcf-f5dae874c730",
    "taxRateId": "50c0d53b-8460-41e6-b4e9-a4e157fc1a64"
  }
]

firstBillingDate

string

First billing date

Example:

"2022-02-02"

purchaseOrderNumber

string

Optional purchase order number to be added to invoices

Example:

"PO123"

reference

string

Optional reference to be added to invoices

Example:

"ref"

label

string

Optional label

Example:

"label"

recurrenceDayOfMonth

integer

The day of the month on which billing recurs

Example:

1

lastInvoiceId

string

ID of the last invoice (if there has been one)

Example:

"bdbf78a5-b007-4d46-aa7d-d0417a649d64"

archivedAt

string

Time at which the schedule was archived, in ISO 8601 format.

Example:

"2022-06-28T16:47:00Z"

contractId

string

Optional ID of the contract used to create this billing schedule

Example:

"0194d091-f65b-7b98-b75f-a923aa0f5b1a"

Activate Billing Schedule Validate taxes on a billing schedule

Copy
curl --request POST \
  --url https://eu.sequencehq.com/api/billing-schedules/{billingScheduleId}/archive \
  --header 'Authorization: <authorization>'

Copy
{
  "id": "b102e007-f5d7-4b1a-8a1d-9a51135ae73b",
  "customerId": "cca32597-b6b0-4499-9669-128aef8702e4",
  "status": "ACTIVE",
  "startDate": "2022-01-01",
  "endDate": "2022-12-01",
  "taxRates": [
    {
      "priceId": "bc61d4b8-e9d6-4f4a-9bcf-f5dae874c730",
      "taxRateId": "50c0d53b-8460-41e6-b4e9-a4e157fc1a64"
    }
  ],
  "firstBillingDate": "2022-02-02",
  "autoIssueInvoices": false,
  "purchaseOrderNumber": "PO123",
  "reference": "ref",
  "label": "label",
  "recurrenceDayOfMonth": 1,
  "prices": [
    {
      "id": "bc61d4b8-e9d6-4f4a-9bcf-f5dae874c730",
      "productId": "f409d651-c475-4142-aafd-a5d2bd74d4f9",
      "name": "Demo Product",
      "currency": "GBP",
      "structure": {
        "pricePerUnit": "0.25",
        "usageMetricId": "04c62961-04ba-48e6-b985-758bb7d3e712",
        "isPricePercentage": false,
        "pricingType": "LINEAR"
      },
      "billingFrequency": "MONTHLY",
      "billingType": "IN_ARREARS",
      "createdAt": "2022-06-28T16:47:00Z",
      "updatedAt": "2022-06-28T16:47:00Z",
      "integrationIds": [],
      "customMetricParameters": [
        {
          "parameterId": "94703530-1293-479b-bd37-ccad42fd9c8b",
          "value": "10"
        }
      ],
      "listPriceId": "b4d7e884-e007-4183-8355-4771865c5100",
      "status": "ACTIVE"
    }
  ],
  "createdAt": "2022-06-28T16:47:00Z",
  "updatedAt": "2022-06-28T16:47:00Z",
  "lastInvoiceId": "bdbf78a5-b007-4d46-aa7d-d0417a649d64",
  "phases": [
    {
      "id": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
      "name": "Onboarding",
      "createdAt": "2022-06-28T16:47:00Z",
      "billingScheduleId": "b102e007-f5d7-4b1a-8a1d-9a51135ae73b",
      "priceIds": [
        "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"
      ],
      "startDate": "2022-01-01",
      "endDate": "2022-06-30",
      "discounts": [
        {
          "restrictToPrices": [
            "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"
          ],
          "type": "PERCENTAGE",
          "amount": 0.15,
          "message": "15% Discount",
          "separateLineItem": true,
          "seatDiscountType": "ALL_SEATS"
        }
      ],
      "minimums": [
        {
          "id": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
          "sequenceAccountId": "c4602d51-0fb4-4b48-b689-6ba28f540d1e",
          "billingScheduleId": "b102e007-f5d7-4b1a-8a1d-9a51135ae73b",
          "phaseId": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
          "amount": 100,
          "restrictToPrices": [
            "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8"
          ],
          "createdAt": "2022-06-28T16:47:00Z",
          "updatedAt": "2022-06-28T16:47:00Z"
        }
      ],
      "recurrencePreference": "CONTINUE_FROM_PREVIOUS_PHASE",
      "phasePriceMetadata": [
        {
          "priceId": "6dc54805-0ac8-4f17-9341-4d3f2db9dcd8",
          "arrCalculation": "INCLUDE"
        }
      ]
    }
  ],
  "archivedAt": "2022-06-28T16:47:00Z",
  "rollUpBilling": false,
  "integrationIds": [
    {
      "service": "Salesforce",
      "id": "a0CQy00000Ipz5VMAR",
      "lastSynced": "2024-08-14T17:14:17Z",
      "url": "https://sequence-b-dev-ed.develop.my.salesforce.com/lightning/r/sequence__Billing_Schedule__c/a0CQy00000Ipz5VMAR/view",
      "isPending": false
    }
  ],
  "attachmentAssets": [
    {
      "id": "e007e884-5100-4183-8355-4771865cb4dd",
      "createdBy": "94703530-1293-479b-bd37-ccad42fd9c8b",
      "type": "IMAGE",
      "format": "PNG",
      "fileName": "my-image.png",
      "fileSizeBytes": 12345,
      "url": "https://assets.sequencehq.com/018f9ad5-4192-76d7-aea5-d80a9018eded/images/e007e884-5100-4183-8355-4771865cb4dd.png",
      "createdAt": "2022-06-28T16:47:00Z"
    }
  ],
  "contractId": "0194d091-f65b-7b98-b75f-a923aa0f5b1a"
}