Invoices

Create an invoice

Changed on

Create a new invoice

post/invoices

Request

  • Base URL
    https://sandbox.sequencehq.com/api
  • URL
    https://sandbox.sequencehq.com/api/invoices
  • Auth
    none declared. Required headers: Authorization

Headers

Authorizationstring required

Your API credentials. Eg. Basic {credentials}.

sequence-version'2024-07-30'

Use this header to select an API version

Request body

billingScheduleIdstring

Billing Schedule ID

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
dueDatestring

Due date

purchaseOrderNumberstring

Purchase order number

referencestring

Reference

customerEmailsstring[]

Customer email addresses, used for sending the Invoice if provided

customerLegalCompanyNamestring

Customer's legal company name

memostring

Invoice memo

paymentOptionsInvoicePaymentOption[]

Invoice payment options

customerIdstring required

The ID of the Customer this invoice is linked to

creditBalancesstring

Credit balances

billingRunIdstring

Billing Run ID

accountingDatestring

Accounting date

attachmentAssetIdsstring[]

Attachment asset IDs

Example request

{
  "billingScheduleId": "fe2fcd0b-4c53-45c7-b2ae-b6c1a7d21e95",
  "currency": "GBP",
  "dueDate": "2022-09-30",
  "purchaseOrderNumber": "PO123",
  "reference": "ref",
  "customerEmails": [
    "customer.user.a@example.com",
    "customer.user.b@example.com"
  ],
  "customerLegalCompanyName": "Facebook",
  "customerBillingAddress": {
    "line1": "Flat 1",
    "line2": "15 Yemen Road",
    "town": "Yemen",
    "state": "CA",
    "postcode": "YE1 2YE",
    "country": "YE"
  },
  "customerShippingAddress": {
    "line1": "742 Evergreen Terrace",
    "town": "Springfield",
    "state": "CA",
    "postcode": "12345",
    "country": "US"
  },
  "memo": "Thanks",
  "paymentOptions": [
    "BANK_TRANSFER"
  ],
  "billingPeriod": {
    "start": "2022-10-01",
    "endInclusive": "2022-10-30"
  },
  "customerId": "61b083e0-1faa-47ca-9aeb-6205da8f6c47",
  "metadata": [
    {
      "key": "example-label",
      "value": "label-value"
    }
  ],
  "creditBalances": "Verification 2 credit balance: 7/7 (expiring on 4 May 2023)",
  "billingRunId": "53ff21c8-4872-46c4-83bf-517d54876945",
  "accountingDate": "2022-09-30",
  "attachmentAssetIds": [
    "99874519-25ce-46ff-8823-093115aa7222"
  ]
}

Response

Created

idstring required

Invoice ID

sequenceAccountIdstring required

Sequence Account ID

billingScheduleIdstring

Billing Schedule ID

billingRunIdstring

Billing Run ID

status'IN_PROGRESS' | 'DRAFT' | 'FINAL' | 'SENT' | 'VOIDED' 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' required
invoiceNumberstring

Invoice number

issueDatestring

Issue date

dueDatestring

Due date

purchaseOrderNumberstring

Purchase order number

referencestring

Reference

customerEmailsstring[] required

Customer email addresses, used for sending the Invoice if provided

customerLegalCompanyNamestring required

Customer's legal company name

memostring

Invoice memo

paymentOptionsInvoicePaymentOption[]

Invoice payment options

customerIdstring required

The ID of the Customer this invoice is linked to

totalTaxstring required

Total tax, in decimal format of the Invoice's currency

netTotalstring required

Net total, in decimal format of the Invoice's currency

grossTotalstring required

Gross total, in decimal format of the Invoice's currency

customerTaxIdstring

Customer's tax ID

paymentStatus'UNPAID' | 'PARTIALLY_PAID' | 'PAID' | 'UNCOLLECTIBLE' required
createdAtstring required

Creation time

updatedAtstring required

Updated time

creditNoteIdsstring[] required

IDs of linked credit notes (if any)

creditBalancesstring

Credit balances

dunningStatus'SCHEDULED' | 'OVERDUE_CHECK_SCHEDULED' | 'COMPLETED' | 'FAILED' | 'NOT_REQUIRED'
accountingDatestring required

Accounting date

calculatedAtstring

Time this invoice was last calculated (applicable for invoices generated by billing engine only)

customerTaxStatus'TAXED' | 'TAX_EXEMPT' | 'REVERSE_CHARGED'
isCustomerArchivedboolean required

isCustomerArchived

balancestring

Outstanding amount owed on this invoice

balanceVersioninteger

Ledger version of the balance. Advances each time the balance changes; null when the invoice has no ledger balance.

appliedCreditGrantTaxstring

Total tax credited to this invoice alongside its applied credit grants. Zero where no tax was credited, and absent when invoice's ledger balance not yet initialised. Tax on applied credit notes not included, as they carry their own tax. Rounded to currency scale for display.

projectedAmountDuestring required

What this invoice is expected to owe once projectedCreditGrants is applied to it, and grossTotal itself where nothing is projected, rounded to the currency's scale. Nets off the projected credit only: tax credited alongside those grants is not deducted, so a finalised invoice owes this less its appliedCreditGrantTax. An estimate that is only locked in at finalisation.

paymentTermDaysinteger nullable required

Payment terms in days. The due date is computed from these terms.

dueDateSource'MANUAL' | 'CALCULATED' required
dueDateStatus'SET' | 'PENDING' required

Example response

{
  "id": "6cedbb5e-4f77-4217-b8d4-020e7e4d33c9",
  "sequenceAccountId": "68233908-402a-43b4-8952-1c2ab0ef0b25",
  "billingScheduleId": "fe2fcd0b-4c53-45c7-b2ae-b6c1a7d21e95",
  "billingRunId": "9c5fdd27-1f7a-41e7-ab67-14f65272a853",
  "status": "DRAFT",
  "currency": "GBP",
  "invoiceNumber": "INV00001",
  "issueDate": "2022-09-15",
  "dueDate": "2022-09-30",
  "purchaseOrderNumber": "PO123",
  "reference": "ref",
  "customerEmails": [
    "customer.user.a@example.com",
    "customer.user.b@example.com"
  ],
  "customerLegalCompanyName": "Facebook",
  "customerBillingAddress": {
    "line1": "Flat 1",
    "line2": "15 Yemen Road",
    "town": "Yemen",
    "state": "CA",
    "postcode": "YE1 2YE",
    "country": "YE"
  },
  "customerShippingAddress": {
    "line1": "742 Evergreen Terrace",
    "town": "Springfield",
    "state": "CA",
    "postcode": "12345",
    "country": "US"
  },
  "memo": "Thanks",
  "paymentOptions": [
    "BANK_TRANSFER"
  ],
  "billingPeriod": {
    "start": "2022-10-01",
    "endInclusive": "2022-10-30"
  },
  "customerId": "61b083e0-1faa-47ca-9aeb-6205da8f6c47",
  "totalTax": "2.50",
  "netTotal": "51.20",
  "grossTotal": "101.23",
  "metadata": [
    {
      "key": "example-label",
      "value": "label-value"
    }
  ],
  "customerTaxId": "TAX123",
  "paymentStatus": "UNPAID",
  "createdAt": "2022-10-30T00:00:00Z",
  "updatedAt": "2022-10-30T00:00:00Z",
  "creditNoteIds": [
    "af60cab3-812d-4250-a051-0fb7133a00c7"
  ],
  "linkedServices": [
    {
      "externalId": "123",
      "externalService": "Xero",
      "syncTime": "2022-06-28T16:47:00Z",
      "externalUrl": "https://invoicing.xero.com/view/85e52542-3e54-4f0d-872b-33bba11a0504"
    }
  ],
  "merchantDetails": {
    "address": {
      "line1": "The White House",
      "line2": "1600 Pennsylvania Avenue",
      "town": "Washington, D.C.",
      "state": "CA",
      "postcode": "20500",
      "country": "US"
    },
    "phoneNumber": "0800001066",
    "email": "finance@example.com",
    "taxId": "TAX60",
    "iban": "GB33BUKB20201555555555",
    "ukAccountDetails": {
      "sortCode": "000000",
      "accountNumber": "12345678"
    },
    "usAchDetails": {
      "accountNumber": "12345678",
      "accountName": "John Doe",
      "bankName": "Chase",
      "bankRoutingNumber": "123456789"
    },
    "usWireDetails": {
      "accountNumber": "12345678",
      "accountName": "John Doe",
      "bankName": "Chase",
      "bankRoutingNumber": "123456789",
      "swiftCode": "CHASUS33",
      "bankAddress": {
        "line1": "JP Morgan Chase",
        "town": "New York City",
        "state": "NY",
        "postcode": "10017",
        "country": "US"
      }
    },
    "caBankAccountDetails": {
      "transitNumber": "123",
      "institutionNumber": "12345",
      "accountNumber": "1234567"
    },
    "canadianInternationalDestination": {
      "legalName": "John Doe",
      "accountNumber": "12345678",
      "transitNumber": "12345",
      "bankName": "Chase",
      "bankAddress": {
        "line1": "JP Morgan Chase",
        "town": "New York City",
        "state": "NY",
        "postcode": "10017",
        "country": "US"
      },
      "institutionNumber": "123",
      "swiftCode": "CHASUS33",
      "intermediaryBank": {
        "bankName": "Chase",
        "bankAddress": {
          "line1": "JP Morgan Chase",
          "town": "New York City",
          "state": "NY",
          "postcode": "10017",
          "country": "US"
        },
        "swiftCode": "CHASUS33",
        "routingNumber": "123456789"
      }
    },
    "australianDestination": {
      "legalName": "John Doe",
      "accountNumber": "12345678",
      "swiftCode": "CHASUS33",
      "bsb": "123456"
    },
    "swedishBankgiroDestination": {
      "bankgiroNumber": "123-4567",
      "accountName": "The Merchant"
    },
    "logoUrl": "logo",
    "legalCompanyName": "The Merchant",
    "primaryColour": "#000000",
    "customFields": [
      {
        "key": "example-label",
        "value": "label-value"
      }
    ],
    "includeBeneficiaryAddressInPaymentDetails": false
  },
  "creditBalances": "Verification 2 credit balance: 7/7 (expiring on 4 May 2023)",
  "dunningStatus": "SCHEDULED",
  "accountingDate": "2022-09-30",
  "calculatedAt": "2022-09-30T00:00:00Z",
  "customerTaxStatus": "TAXED",
  "renderSettings": {
    "paymentLinkDisplay": "HIDE_PAYMENT_LINK"
  },
  "isCustomerArchived": false,
  "attachmentAssets": [
    {
      "id": "4b36a61e-425e-4640-aa26-6224c577b613",
      "createdBy": "94703530-1293-479b-bd37-ccad42fd9c8b",
      "createdByType": "SEQUENCE_USER",
      "type": "DOCUMENT",
      "format": "PDF",
      "fileName": "my-document.pdf",
      "fileSizeBytes": 12345,
      "url": "https://assets.sequencehq.com/6cedbb5e-4f77-4217-b8d4-020e7e4d33c9/documents/4B36A61E-425E-4640-AA26-6224C577B613.pdf",
      "createdAt": "2022-06-28T16:47:00Z"
    }
  ],
  "balance": "1000.00",
  "balanceVersion": 0,
  "integrationPaymentStatuses": {
    "stripe": "PAID",
    "goCardless": "CANCELLED"
  },
  "appliedCreditNotes": [
    {
      "id": "8f3a5b1e-0c2d-4e6f-8a9b-1c2d3e4f5a6b",
      "creditNoteNumber": "CN00001",
      "netTotal": "41.67",
      "totalTax": "8.33",
      "grossTotal": "50.00",
      "lineItems": [
        {
          "name": "Adjustment",
          "netTotal": "41.67",
          "grossTotal": "50.00",
          "invoiceLineItemIds": [
            "2d4f6a8b-1c3e-4f5a-9b7d-8e6f5a4b3c2d"
          ]
        }
      ]
    }
  ],
  "appliedCreditGrants": [
    {
      "creditGrantId": "0198b2c9-5f41-7c3d-9a8e-2b4c6d8e0f13",
      "creditGrantName": "Q3 prepaid credit",
      "amount": "820.00",
      "taxAmount": "0.00",
      "status": "APPLIED"
    }
  ],
  "appliedCreditGrantTax": "164.00",
  "projectedCreditGrants": [
    {
      "creditGrantId": "0198b2c9-5f41-7c3d-9a8e-2b4c6d8e0f13",
      "creditGrantName": "Q3 prepaid credit",
      "amount": "30.00"
    }
  ],
  "projectedAmountDue": "71.23",
  "paymentAllocations": [
    {
      "paymentId": "3f9c1a7d-6b2e-4c8a-9d5f-0e1a2b3c4d5e",
      "amount": "50.00",
      "allocatedAt": "2022-10-30T00:00:00Z",
      "paidAt": "2022-10-29T00:00:00Z",
      "origin": "MANUAL"
    }
  ],
  "paymentTermDays": 30,
  "dueDateSource": "CALCULATED",
  "dueDatePolicy": {
    "paymentTermDays": 30,
    "type": "PAYMENT_TERMS"
  },
  "dueDateStatus": "SET"
}

Changes

  • 76af807ed781Revision changes
    • breaking

      the // response's property type changed from no type to object for status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

  • 78761eec0072Revision changes
    • breaking

      the // response's property type changed from object to no type for status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • info

      added the optional property / to the response with the status