Create an invoice

curl --request POST \
  --url https://api.yorlet.com/v1/invoices \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "application": "<string>",
  "apply_customer_balance": true,
  "assignee": "<string>",
  "auto_advance": true,
  "coupon": "<string>",
  "currency": "gbp",
  "custom_fields": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "customer": "<string>",
  "days_until_due": 123,
  "default_payment_method": "<string>",
  "description": "<string>",
  "due_date": 123,
  "line_items": [
    {
      "amount": 123,
      "currency": "<string>",
      "customer": "<string>",
      "description": "<string>",
      "tax_percent": 50,
      "apply_after": 123,
      "metadata": {},
      "period_end": 123,
      "period_start": 123,
      "price": "<string>",
      "tax_rate": "<string>",
      "transfer_destination": "<string>",
      "unit": "<string>"
    }
  ],
  "metadata": {},
  "send_finalization_email": true
}
'

{
  "id": "<string>",
  "created": 123,
  "object": "invoice",
  "application": "<string>",
  "assignee": "<string>",
  "credit_grant": "<string>",
  "credit_grant_creation": {
    "enabled": true,
    "credit_grant_data": {
      "applicability_config": {
        "limits": {
          "max_credit_per_invoice_item": 123
        }
      },
      "name": "<string>"
    }
  },
  "currency": "<string>",
  "custom_fields": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "customer": "<string>",
  "customer_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "country": "<string>",
    "postal_code": "<string>",
    "state": "<string>"
  },
  "customer_email": "<string>",
  "customer_name": "<string>",
  "default_payment_method": "<string>",
  "description": "<string>",
  "discount": {},
  "discount_amount": 123,
  "due_date": 123,
  "ending_balance": 123,
  "finalized_at": 123,
  "footer": "<string>",
  "from_invoice": {
    "action": "<string>",
    "invoice": "<string>"
  },
  "hosted_invoice_url": "<string>",
  "issuer": {
    "owner": "<string>"
  },
  "last_finalization_error": {
    "code": "<string>",
    "message": "<string>"
  },
  "late_payment_failure_invoice": "<string>",
  "latest_revision": "<string>",
  "marked_uncollectible_at": 123,
  "next_payment_attempt": 123,
  "number": "<string>",
  "number_transfer_reference": "<string>",
  "off_platform_reference": "<string>",
  "optimized_collection_date": 123,
  "paid": true,
  "paid_at": 123,
  "paid_off_platform": true,
  "payment_settings": {
    "payment_method_types": []
  },
  "period": {
    "end": 123,
    "start": 123
  },
  "source_dispute": "<string>",
  "starting_balance": 123,
  "subscription": "<string>",
  "transaction": "<string>",
  "transfer_error": {
    "message": "<string>",
    "reason": "<string>"
  },
  "voided_at": 123,
  "account": "<string>",
  "deleted": false,
  "amount_due": 0,
  "amount_paid": 0,
  "amount_remaining": 0,
  "applied_balance": 0,
  "apply_customer_balance": false,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "late_payment_failure": false,
  "metadata": {},
  "part_payment_amount": 0,
  "pending_part_payment": false,
  "pending_transaction": false,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_excluding_tax": 0,
  "total_pretax_credit_amounts": [],
  "total_tax_amounts": [],
  "transfer_data": []
}

POST

invoices

Create an invoice

curl --request POST \
  --url https://api.yorlet.com/v1/invoices \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "application": "<string>",
  "apply_customer_balance": true,
  "assignee": "<string>",
  "auto_advance": true,
  "coupon": "<string>",
  "currency": "gbp",
  "custom_fields": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "customer": "<string>",
  "days_until_due": 123,
  "default_payment_method": "<string>",
  "description": "<string>",
  "due_date": 123,
  "line_items": [
    {
      "amount": 123,
      "currency": "<string>",
      "customer": "<string>",
      "description": "<string>",
      "tax_percent": 50,
      "apply_after": 123,
      "metadata": {},
      "period_end": 123,
      "period_start": 123,
      "price": "<string>",
      "tax_rate": "<string>",
      "transfer_destination": "<string>",
      "unit": "<string>"
    }
  ],
  "metadata": {},
  "send_finalization_email": true
}
'

{
  "id": "<string>",
  "created": 123,
  "object": "invoice",
  "application": "<string>",
  "assignee": "<string>",
  "credit_grant": "<string>",
  "credit_grant_creation": {
    "enabled": true,
    "credit_grant_data": {
      "applicability_config": {
        "limits": {
          "max_credit_per_invoice_item": 123
        }
      },
      "name": "<string>"
    }
  },
  "currency": "<string>",
  "custom_fields": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "customer": "<string>",
  "customer_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "country": "<string>",
    "postal_code": "<string>",
    "state": "<string>"
  },
  "customer_email": "<string>",
  "customer_name": "<string>",
  "default_payment_method": "<string>",
  "description": "<string>",
  "discount": {},
  "discount_amount": 123,
  "due_date": 123,
  "ending_balance": 123,
  "finalized_at": 123,
  "footer": "<string>",
  "from_invoice": {
    "action": "<string>",
    "invoice": "<string>"
  },
  "hosted_invoice_url": "<string>",
  "issuer": {
    "owner": "<string>"
  },
  "last_finalization_error": {
    "code": "<string>",
    "message": "<string>"
  },
  "late_payment_failure_invoice": "<string>",
  "latest_revision": "<string>",
  "marked_uncollectible_at": 123,
  "next_payment_attempt": 123,
  "number": "<string>",
  "number_transfer_reference": "<string>",
  "off_platform_reference": "<string>",
  "optimized_collection_date": 123,
  "paid": true,
  "paid_at": 123,
  "paid_off_platform": true,
  "payment_settings": {
    "payment_method_types": []
  },
  "period": {
    "end": 123,
    "start": 123
  },
  "source_dispute": "<string>",
  "starting_balance": 123,
  "subscription": "<string>",
  "transaction": "<string>",
  "transfer_error": {
    "message": "<string>",
    "reason": "<string>"
  },
  "voided_at": 123,
  "account": "<string>",
  "deleted": false,
  "amount_due": 0,
  "amount_paid": 0,
  "amount_remaining": 0,
  "applied_balance": 0,
  "apply_customer_balance": false,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "late_payment_failure": false,
  "metadata": {},
  "part_payment_amount": 0,
  "pending_part_payment": false,
  "pending_transaction": false,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_excluding_tax": 0,
  "total_pretax_credit_amounts": [],
  "total_tax_amounts": [],
  "transfer_data": []
}

Authorizations

Authorization

string

header

required

API Key authentication. Use "Bearer YOUR_API_KEY".

Body

application/json

collection_method

enum<string>

required

Either charge_automatically, or send_invoice. Determines how the invoice will be collected.

Available options:

charge_automatically,

send_invoice

application

string | null

The identifier of the application associated with this invoice.

apply_customer_balance

boolean

Whether to apply any available customer balance to this invoice.

assignee

string | null

The identifier of the user the invoice is assigned to.

auto_advance

boolean

Controls whether the invoice is automatically finalized and progressed through its lifecycle.

coupon

string

The ID of the coupon to apply to this invoice.

credit_grant_creation

object

Configuration for creating a credit grant when the invoice is paid.

Show child attributes

currency

enum<string> | null

Three-letter ISO currency code, in lowercase. Must be a supported currency.

Available options:

gbp,

usd,

eur,

sek,

null

Example:

"gbp"

custom_fields

object[] | null

Custom fields to display on the invoice (maximum of 4).

Maximum array length: 4

Show child attributes

customer

string

The ID of the customer who will be billed.

days_until_due

integer

The number of days from when the invoice is created until it is due. Valid only for invoices where collection_method=send_invoice.

default_payment_method

string | null

ID of the default payment method for the invoice. It must belong to the customer associated with the invoice.

description

string | null

An arbitrary string attached to the object. Often useful for displaying to users.

due_date

integer | null

The date on which payment for this invoice is due. Valid only for invoices where collection_method=send_invoice.

from_invoice

object

Revise an existing invoice. The new invoice will be created in status=draft.

Show child attributes

issuer

object

The party that issues the invoice (the platform itself or an owner).

Show child attributes

line_items

object[]

A list of up to 20 line items to include on this invoice.

Maximum array length: 20

Show child attributes

metadata

object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Show child attributes

payment_settings

object

Configuration for the payment options available on the invoice.

Show child attributes

period

object

The period this invoice covers.

Show child attributes

send_finalization_email

boolean

Whether to send an email notification when the invoice is finalized.

Response

200 - application/json

Create an invoice

string

required

Unique identifier for the object.

created

number

required

Time at which the object was created. Measured in seconds since the Unix epoch.

object

enum<string>

required

Available options:

invoice

application

string | null

required

The identifier of the application associated with this invoice.

assignee

string | null

required

The identifier of the user the invoice is assigned to.

billing_reason

enum<string> | null

required

The reason this invoice was created.

Available options:

manual,

subscription,

late_payment_failure,

partial_payment,

null

collection_method

enum<string> | null

required

Either charge_automatically, or send_invoice. Determines how the invoice will be collected.

Available options:

charge_automatically,

send_invoice,

null

credit_grant

required

The credit grant associated with the invoice.

credit_grant_creation

object

required

Configuration for creating a credit grant when the invoice is paid.

Show child attributes

currency

string

required

Three-letter ISO currency code, in lowercase. Must be a supported currency.

custom_fields

object[] | null

required

Custom fields displayed on the invoice.

Maximum array length: 4

Show child attributes

customer

required

The ID of the customer who will be billed.

customer_address

object

required

The customer's address. Used to calculate taxes on the invoice.

Show child attributes

customer_email

string | null

required

The customer's email at the time the invoice was created.

customer_name

string | null

required

The customer's name at the time the invoice was created.

default_payment_method

string | null

required

ID of the default payment method for the invoice. It must belong to the customer associated with the invoice.

description

string | null

required

An arbitrary string attached to the object. Often useful for displaying to users.

discount

object

required

Describes the current discount applied to this invoice, if any.

discount_amount

number

required

The amount of the discount applied to the invoice.

due_date

integer | null

required

The date on which payment for this invoice is due. This value will be null for invoices where collection_method=charge_automatically.

ending_balance

number

required

Ending customer balance after the invoice is finalized. If the invoice has not been finalized yet, this will be null.

finalized_at

integer | null

required

The time when the invoice was finalized.

footer

string | null

required

Footer displayed on the invoice.

from_invoice

object

required

Details of the invoice this invoice was derived from, if any.

Show child attributes

hosted_invoice_url

string | null

required

The URL for the hosted invoice page, which allows customers to view and pay an invoice.

issuer

object

required

The party that issues the invoice (the platform itself or an owner).

Show child attributes

last_finalization_error

object

required

The error encountered during the previous attempt to finalize the invoice.

Show child attributes

late_payment_failure_invoice

string | null

required

The ID of the late payment failure invoice generated for this invoice.

latest_revision

string | null

required

The ID of the latest revision of this invoice.

marked_uncollectible_at

integer | null

required

The time the invoice was marked uncollectible.

next_payment_attempt

integer | null

required

The time at which payment will next be attempted.

number

string | null

required

A unique, identifying string that appears on emails sent to the customer for this invoice.

number_transfer_reference

string | null

required

A reference assigned to the bank transfer for this invoice, used for reconciliation.

off_platform_reference

string | null

required

A reference used when the invoice has been paid off platform.

optimized_collection_date

integer | null

required

The optimized date at which collection should be attempted.

optimized_collection_reason

enum<string> | null

required

The reason the collection date was optimized.

Available options:

bacs_debit,

days_before_collection,

null

paid

boolean

required

Whether payment was successfully collected for this invoice.

paid_at

integer | null

required

The time at which payment was collected for this invoice.

paid_off_platform

boolean

required

Whether the invoice was paid outside of the platform.

payment_settings

object

required

Configuration for the payment options available on the invoice.

Show child attributes

period

object

required

The period this invoice covers.

Show child attributes

source_dispute

string | null

required

The ID of the dispute that this invoice was created from, if any.

starting_balance

number

required

Starting customer balance before the invoice is finalized.

status

enum<string>

required

The status of the invoice.

Available options:

draft,

open,

paid,

uncollectible,

void

subscription

string | null

required

The ID of the subscription that the invoice was created for, if any.

transaction

required

The transaction object created when the invoice was paid, if any.

transfer_error

object

required

The error encountered during the last attempt to transfer funds for this invoice.

Show child attributes

voided_at

integer | null

required

The time at which the invoice was voided.

account

string

The account that the object belongs to. Only returned if the request is made with a valid Yorlet-Context header.

deleted

boolean

default:false

Only returned if the object has been deleted.

amount_due

number

default:0

Final amount due at this time for this invoice.

amount_paid

number

default:0

The amount, in cents, that was paid.

amount_remaining

number

default:0

The difference between amount_due and amount_paid.

applied_balance

number

default:0

The amount of customer balance that has been applied to this invoice.

apply_customer_balance

boolean

default:false

Whether to apply any available customer balance to this invoice.

attempt_count

number

default:0

Number of payment attempts made for this invoice.

attempted

boolean

default:false

Whether an attempt has been made to pay the invoice.

auto_advance

boolean

default:false

Controls whether the invoice is automatically finalized and progressed through its lifecycle.

late_payment_failure

boolean

default:false

Whether the invoice is in a late payment failure state.

metadata

object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Show child attributes

part_payment_amount

number

default:0

The total amount of part payments collected for this invoice.

pending_part_payment

boolean

default:false

Whether a part payment for this invoice is currently pending.

pending_transaction

boolean

default:false

Whether a payment transaction for this invoice is currently pending.

post_payment_credit_notes_amount

number

default:0

Total amount of all post-payment credit notes issued for this invoice.

pre_payment_credit_notes_amount

number

default:0

Total amount of all pre-payment credit notes issued for this invoice.

subtotal

number

default:0

Total of all subscriptions, invoice items, and prorations on the invoice before any discount or tax is applied.

tax

number

default:0

The amount of tax on this invoice.

total

number

default:0

Total after discounts and taxes.

total_excluding_tax

number

default:0

The integer amount in cents representing the total amount of the invoice including all discounts but excluding all tax.

total_pretax_credit_amounts

any[]

Contains pretax credit amounts (ex: discount, credit grants, etc.) that apply to this invoice.

total_tax_amounts

object[]

The aggregate amounts of taxes per tax rate for all line items on this invoice.

Show child attributes

transfer_data

any[]

The transfers associated with this invoice.

The invoice object

Retrieve an invoice