> ## Documentation Index > Fetch the complete documentation index at: https://docs.yorlet.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an invoice > Create an invoice ## OpenAPI ````yaml openapi-billing.json POST /v1/invoices openapi: 3.1.0 info: title: Yorlet Billing API description: APIs for managing invoices, coupons, credit grants, and subscription items. version: 1.0.0 servers: - url: https://api.yorlet.com description: Production - url: https://api.yorlet.io description: Sandbox security: [] paths: /v1/invoices: post: tags: - Invoices summary: Create an invoice description: Create an invoice operationId: invoices_create requestBody: content: application/json: schema: type: object properties: application: type: - string - 'null' description: >- The identifier of the application associated with this invoice. apply_customer_balance: type: boolean description: >- Whether to apply any available customer balance to this invoice. assignee: type: - string - 'null' description: The identifier of the user the invoice is assigned to. auto_advance: type: boolean description: >- Controls whether the invoice is automatically finalized and progressed through its lifecycle. collection_method: type: string enum: - charge_automatically - send_invoice description: >- Either `charge_automatically`, or `send_invoice`. Determines how the invoice will be collected. coupon: type: string description: The ID of the coupon to apply to this invoice. credit_grant_creation: type: object properties: enabled: type: boolean description: >- Whether a credit grant should be created when the invoice is paid. credit_grant_data: type: object properties: applicability_config: type: object properties: limits: type: object properties: max_credit_per_invoice_item: type: integer minimum: 1 description: >- The maximum amount of credit per invoice item. required: - max_credit_per_invoice_item description: Limits that apply to the credit grant. required: - limits description: >- Configuration that controls when and how the credit grant can be applied. name: type: string description: >- The name of the credit grant. This will be displayed to the customer. required: - applicability_config - name description: >- Data used to create the credit grant when the invoice is paid. required: - enabled description: >- Configuration for creating a credit grant when the invoice is paid. currency: type: - string - 'null' enum: - gbp - usd - eur - sek - null description: >- Three-letter ISO currency code, in lowercase. Must be a supported currency. example: gbp custom_fields: type: - array - 'null' items: type: object properties: name: type: string maxLength: 40 description: The name of the custom field. value: type: string maxLength: 140 description: The value of the custom field. required: - name - value maxItems: 4 description: Custom fields to display on the invoice (maximum of 4). customer: type: string description: The ID of the customer who will be billed. days_until_due: type: integer description: >- 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: type: - string - 'null' description: >- ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. description: type: - string - 'null' description: >- An arbitrary string attached to the object. Often useful for displaying to users. due_date: type: - integer - 'null' description: >- The date on which payment for this invoice is due. Valid only for invoices where `collection_method=send_invoice`. from_invoice: type: object properties: action: type: string enum: - revision description: >- The action that derives this invoice from the original invoice. invoice: type: string description: The ID of the invoice this invoice is derived from. required: - action - invoice description: >- Revise an existing invoice. The new invoice will be created in `status=draft`. issuer: type: object properties: owner: type: string description: >- The ID of the owner issuing the invoice. Required when `type` is `owner`. type: type: string enum: - owner - self description: Type of the account referenced by the issuer. required: - type description: >- The party that issues the invoice (the platform itself or an owner). line_items: type: array items: type: object properties: amount: type: integer description: >- The amount to be charged, represented as a whole integer if possible. apply_after: type: integer description: The date after which the invoice item will be applied. currency: type: string description: >- Three-letter ISO currency code, in lowercase. Must be a supported currency. customer: type: string description: The ID of the customer the invoice item is for. description: type: string description: >- The description for the invoice item, to be displayed to the customer. metadata: type: - object - 'null' additionalProperties: type: string description: >- 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. period_end: type: integer description: The end date of the invoice item. period_start: type: integer description: The start date of the invoice item. price: type: string description: The ID of the price object. tax_percent: type: number minimum: 0 maximum: 100 description: >- The tax percentage to use when calculating the tax amount. tax_rate: type: string description: The ID of the tax rate object. transfer_behavior: type: string enum: - automatic - owner - none description: >- The invoice item transfer behavior. The default is automatic. transfer_destination: type: string description: >- ID of the owner that will be the transfer destination. Only allowed when the invoice item transfer behavior is owner. type: type: string enum: - charge - rent - product description: The type of the invoice item. unit: type: - string - 'null' description: The ID of the unit the invoice item is for. required: - amount - currency - customer - description - tax_percent - transfer_behavior - type maxItems: 20 description: A list of up to 20 line items to include on this invoice. metadata: type: - object - 'null' additionalProperties: type: string description: >- 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. payment_settings: type: object properties: payment_method_types: type: array items: type: string enum: - autogiro - bacs_debit - card - card_present - bank_transfer - direct_transfer - gbp_credit_transfer - pay_by_bank - sepa_debit minItems: 1 description: >- The list of payment method types that the customer can use to pay this invoice. required: - payment_method_types description: >- Configuration for the payment options available on the invoice. period: type: object properties: start: type: integer description: >- Start of the usage period during which invoice items were added to this invoice. end: type: integer description: >- End of the usage period during which invoice items were added to this invoice. required: - start - end description: The period this invoice covers. send_finalization_email: type: boolean description: >- Whether to send an email notification when the invoice is finalized. required: - collection_method responses: '200': description: Create an invoice content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the object. created: type: number description: >- Time at which the object was created. Measured in seconds since the Unix epoch. account: type: string description: >- The account that the object belongs to. Only returned if the request is made with a valid Yorlet-Context header. deleted: type: boolean default: false description: Only returned if the object has been deleted. object: type: string enum: - invoice amount_due: type: number default: 0 description: Final amount due at this time for this invoice. amount_paid: type: number default: 0 description: The amount, in cents, that was paid. amount_remaining: type: number default: 0 description: The difference between `amount_due` and `amount_paid`. application: type: - string - 'null' description: >- The identifier of the application associated with this invoice. applied_balance: type: number default: 0 description: >- The amount of customer balance that has been applied to this invoice. apply_customer_balance: type: boolean default: false description: >- Whether to apply any available customer balance to this invoice. assignee: type: - string - 'null' description: The identifier of the user the invoice is assigned to. attempt_count: type: number default: 0 description: Number of payment attempts made for this invoice. attempted: type: boolean default: false description: Whether an attempt has been made to pay the invoice. auto_advance: type: boolean default: false description: >- Controls whether the invoice is automatically finalized and progressed through its lifecycle. billing_reason: type: - string - 'null' enum: - manual - subscription - late_payment_failure - partial_payment - null description: The reason this invoice was created. collection_method: type: - string - 'null' enum: - charge_automatically - send_invoice - null description: >- Either `charge_automatically`, or `send_invoice`. Determines how the invoice will be collected. credit_grant: anyOf: - type: string - type: object additionalProperties: {} - type: 'null' description: The credit grant associated with the invoice. credit_grant_creation: type: object properties: enabled: type: boolean description: >- Whether a credit grant should be created when the invoice is paid. credit_grant_data: type: - object - 'null' properties: applicability_config: type: object properties: limits: type: object properties: max_credit_per_invoice_item: type: number description: >- The maximum amount of credit per invoice item. required: - max_credit_per_invoice_item description: Limits that apply to the credit grant. required: - limits description: >- Configuration that controls when and how the credit grant can be applied. name: type: string description: >- The name of the credit grant. This will be displayed to the customer. required: - applicability_config - name description: >- Data used to create the credit grant when the invoice is paid. required: - enabled - credit_grant_data description: >- Configuration for creating a credit grant when the invoice is paid. currency: type: string description: >- Three-letter ISO currency code, in lowercase. Must be a supported currency. custom_fields: type: - array - 'null' items: type: object properties: name: type: string maxLength: 40 description: The name of the custom field. value: type: string maxLength: 140 description: The value of the custom field. required: - name - value maxItems: 4 description: Custom fields displayed on the invoice. customer: anyOf: - type: string - type: object additionalProperties: {} description: The ID of the customer who will be billed. customer_address: type: - object - 'null' properties: line1: type: - string - 'null' line2: type: - string - 'null' city: type: - string - 'null' country: type: - string - 'null' postal_code: type: - string - 'null' state: type: - string - 'null' description: >- The customer's address. Used to calculate taxes on the invoice. customer_email: type: - string - 'null' description: The customer's email at the time the invoice was created. customer_name: type: - string - 'null' description: The customer's name at the time the invoice was created. default_payment_method: type: - string - 'null' description: >- ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. description: type: - string - 'null' description: >- An arbitrary string attached to the object. Often useful for displaying to users. discount: type: - object - 'null' properties: {} description: >- Describes the current discount applied to this invoice, if any. discount_amount: type: number description: The amount of the discount applied to the invoice. due_date: type: - integer - 'null' description: >- The date on which payment for this invoice is due. This value will be null for invoices where `collection_method=charge_automatically`. ending_balance: type: number description: >- Ending customer balance after the invoice is finalized. If the invoice has not been finalized yet, this will be null. finalized_at: type: - integer - 'null' description: The time when the invoice was finalized. footer: type: - string - 'null' description: Footer displayed on the invoice. from_invoice: type: object properties: action: type: - string - 'null' description: >- The action that derived this invoice from the original invoice. invoice: type: - string - 'null' description: The ID of the invoice this invoice was derived from. required: - action - invoice description: >- Details of the invoice this invoice was derived from, if any. hosted_invoice_url: type: - string - 'null' description: >- The URL for the hosted invoice page, which allows customers to view and pay an invoice. issuer: type: object properties: owner: type: string description: >- The ID of the owner issuing the invoice. Required when `type` is `owner`. type: type: string enum: - owner - self description: Type of the account referenced by the issuer. required: - type description: >- The party that issues the invoice (the platform itself or an owner). last_finalization_error: type: - object - 'null' properties: code: type: - string - 'null' description: >- The error code for the most recent finalization attempt. message: type: - string - 'null' description: >- The error message for the most recent finalization attempt. required: - code - message description: >- The error encountered during the previous attempt to finalize the invoice. late_payment_failure: type: boolean default: false description: Whether the invoice is in a late payment failure state. late_payment_failure_invoice: type: - string - 'null' description: >- The ID of the late payment failure invoice generated for this invoice. latest_revision: type: - string - 'null' description: The ID of the latest revision of this invoice. marked_uncollectible_at: type: - integer - 'null' description: The time the invoice was marked uncollectible. metadata: type: - object - 'null' additionalProperties: type: string description: >- 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. next_payment_attempt: type: - integer - 'null' description: The time at which payment will next be attempted. number: type: - string - 'null' description: >- A unique, identifying string that appears on emails sent to the customer for this invoice. number_transfer_reference: type: - string - 'null' description: >- A reference assigned to the bank transfer for this invoice, used for reconciliation. off_platform_reference: type: - string - 'null' description: >- A reference used when the invoice has been paid off platform. optimized_collection_date: type: - integer - 'null' description: >- The optimized date at which collection should be attempted. optimized_collection_reason: type: - string - 'null' enum: - bacs_debit - days_before_collection - null description: The reason the collection date was optimized. paid: type: boolean description: >- Whether payment was successfully collected for this invoice. paid_at: type: - integer - 'null' description: The time at which payment was collected for this invoice. paid_off_platform: type: boolean description: Whether the invoice was paid outside of the platform. part_payment_amount: type: number default: 0 description: >- The total amount of part payments collected for this invoice. payment_settings: type: object properties: payment_method_types: type: - array - 'null' items: type: string enum: - autogiro - bacs_debit - card - card_present - bank_transfer - direct_transfer - gbp_credit_transfer - pay_by_bank - sepa_debit description: >- The list of payment method types that the customer can use to pay this invoice. required: - payment_method_types description: >- Configuration for the payment options available on the invoice. pending_part_payment: type: boolean default: false description: >- Whether a part payment for this invoice is currently pending. pending_transaction: type: boolean default: false description: >- Whether a payment transaction for this invoice is currently pending. period: type: object properties: end: type: integer description: >- End of the usage period during which invoice items were added to this invoice. start: type: integer description: >- Start of the usage period during which invoice items were added to this invoice. required: - end - start description: The period this invoice covers. post_payment_credit_notes_amount: type: number default: 0 description: >- Total amount of all post-payment credit notes issued for this invoice. pre_payment_credit_notes_amount: type: number default: 0 description: >- Total amount of all pre-payment credit notes issued for this invoice. source_dispute: type: - string - 'null' description: >- The ID of the dispute that this invoice was created from, if any. starting_balance: type: number description: Starting customer balance before the invoice is finalized. status: type: string enum: - draft - open - paid - uncollectible - void description: The status of the invoice. subtotal: type: number default: 0 description: >- Total of all subscriptions, invoice items, and prorations on the invoice before any discount or tax is applied. subscription: type: - string - 'null' description: >- The ID of the subscription that the invoice was created for, if any. tax: type: number default: 0 description: The amount of tax on this invoice. total: type: number default: 0 description: Total after discounts and taxes. total_excluding_tax: type: number default: 0 description: >- The integer amount in cents representing the total amount of the invoice including all discounts but excluding all tax. total_pretax_credit_amounts: type: array items: {} default: [] description: >- Contains pretax credit amounts (ex: discount, credit grants, etc.) that apply to this invoice. total_tax_amounts: type: array items: type: object properties: amount: type: integer description: The amount, in cents, of the tax. tax_rate: type: string description: >- The ID of the tax rate associated with this tax amount. taxable_amount: type: integer default: 0 description: The amount on which tax is calculated, in cents. required: - amount - tax_rate default: [] description: >- The aggregate amounts of taxes per tax rate for all line items on this invoice. transaction: anyOf: - type: string - type: object additionalProperties: {} - type: 'null' description: >- The transaction object created when the invoice was paid, if any. transfer_data: type: array items: type: object properties: id: type: string description: The ID of the transfer. object: type: string description: The object type of the transfer. amount: type: number description: The amount of the transfer. description: type: string description: The description of the transfer. destination: type: string description: The destination of the transfer. failure_code: type: - string - 'null' description: The failure code of the transfer. part_payment: type: - string - 'null' description: The part payment of the transfer. source_invoice_item: type: string description: The source invoice item of the transfer. status: type: string description: The status of the transfer. tax_reporting: type: - object - 'null' properties: tax: type: number description: The tax of the transfer. tax_percent: type: number description: The tax percent of the transfer. required: - tax - tax_percent description: The tax reporting of the transfer. unit: type: - string - 'null' description: The unit of the transfer. required: - id - object - amount - description - destination - failure_code - part_payment - source_invoice_item - status - tax_reporting - unit description: The transfers associated with this invoice. transfer_error: type: - object - 'null' properties: message: type: - string - 'null' description: >- The error message for the most recent transfer attempt. reason: type: - string - 'null' description: The reason the transfer failed. required: - message - reason description: >- The error encountered during the last attempt to transfer funds for this invoice. voided_at: type: - integer - 'null' description: The time at which the invoice was voided. required: - id - created - object - application - assignee - billing_reason - collection_method - credit_grant - credit_grant_creation - currency - custom_fields - customer - customer_address - customer_email - customer_name - default_payment_method - description - discount - discount_amount - due_date - ending_balance - finalized_at - footer - from_invoice - hosted_invoice_url - issuer - last_finalization_error - late_payment_failure_invoice - latest_revision - marked_uncollectible_at - next_payment_attempt - number - number_transfer_reference - off_platform_reference - optimized_collection_date - optimized_collection_reason - paid - paid_at - paid_off_platform - payment_settings - period - source_dispute - starting_balance - status - subscription - transaction - transfer_data - transfer_error - voided_at security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API Key authentication. Use "Bearer YOUR_API_KEY". ````