Finalize an invoice

Developing

POST

/v1/invoices/{id}/finalize

Wooshpay automatically finalizes drafts before sending and attempting payment on invoices. However, if you’d like to finalize a draft invoice manually, you can do so using this method.

Returns an invoice object with status=open.

Request

Authorization

Send your HTTP requests with an

Authorization

header that contains the word Basic followed by a space and a base64-encoded string username:password

Example:

Authorization: Basic *****************

Path Params

string

required

Header Params

string

required

Default:

application/json

Content-Type

string

required

Default:

application/json

Body Params application/json

auto_advance

boolean

optional

Controls whether Wooshpay performs automatic collection of the invoice. If false, the invoice’s state doesn’t automatically advance without an explicit action.

Example

{
  "auto_advance": true
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://apitest.wooshpay.com/v1/invoices//finalize' \
--header 'Accept;' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Og==' \
--data-raw '{
    "auto_advance": true
}'

Responses

🟢200OK

application/json

Body

string

optional

currency

string

optional

Three-letter ISO currency code

customer

string

optional

The ID of the customer who will be billed.

object

string

optional

String representing the object’s type. Objects of the same type share the same value.

auto_advance

boolean

optional

If false, the invoice’s state doesn’t automatically advance without an explicit actio

charge

string

optional

ID of the latest charge generated for this invoice, if any.

collection_method

string

optional

Either charge_automatically, or send_invoice

description

string

optional

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

hosted_invoice_url

string

optional

The URL for the hosted invoice page, which allows customers to view and pay an invoice. If the invoice has not been finalized yet, this will be null.

lines

object

optional

list. The individual line items that make up the invoice. lines is sorted as follows: (1) pending invoice items (including prorations) in reverse chronological order, (2) subscription items in reverse chronological order, and (3) invoice items added after invoice creation in chronological order.

object

string

optional

value is "list"

data

array [object {18}]

optional

contains: line_item object. Details about each object.

has_more

boolean

optional

True if this list has another page of items after this one that can be fetched

url

string

optional

The URL where this list can be accessed.

metadata

object

optional

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_intent

string

optional

EXPANDABLE. The PaymentIntent associated with this invoice. The PaymentIntent is generated when the invoice is finalized, and can then be used to pay the invoice. Note that voiding an invoice will cancel the PaymentIntent.

period_end

string

optional

timestamp. End of the usage period during which invoice items were added to this invoice.

period_start

string

optional

timestamp. Start of the usage period during which invoice items were added to this invoice.

status

string

optional

The status of the invoice, one of draft, open, paid, uncollectible, or void

subscription

string

optional

EXPANDABLE. The subscription that this invoice was prepared for, if any.

account_country

string

optional

The country of the business associated with this invoice, most often the business creating the invoice.

account_name

string

optional

The public name of the business associated with this invoice, most often the business creating the invoice.

amount_due

integer

optional

Final amount due at this time for this invoice. If the invoice’s total is smaller than the minimum charge amount, for example, or if there is account credit that can be applied to the invoice, the amount_due may be 0. If there is a positive starting_balance for the invoice (the customer owes money), the amount_due will also take that into account. The charge that gets generated for the invoice will be for the amount specified in amount_due.

amount_paid

integer

optional

amount_precision

integer

optional

This field controls the precision of the amount displayed on the invoice. If amount_precision is set to 3, it means the smallest decimal for the amount parameter is 3. This field only affects the display. For actual deductions, please refer to the minimum unit of the supported currency. The default value is the minimum unit of the currency.

billing_reason

enum<string>

optional

Indicates the reason why the invoice was created. manual: Unrelated to a subscription, for example, created via the invoice editor. subscription: No longer in use. Applies to subscriptions from before May 2018 where no distinction was made between updates, cycles, and thresholds. subscription_create: A new subscription was created. subscription_cycle: A subscription advanced into a new period. subscription_threshold: A subscription reached a billing threshold. subscription_update: A subscription was updated. upcoming: Reserved for simulated invoices, per the upcoming invoice endpoint.

Allowed values:

manualsubscriptionsubscription_createsubscription_cyclesubscription_thresholdsubscription_updateupcoming

created

integer

optional

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

custom_fields

array [object {2}]

optional

A list of up to 4 custom fields to be displayed on the invoice.

name

string

optional

The name of the custom field.

value

string

optional

The value of the custom field.

customer_address

object (Address)

optional

The customer’s address. Until the invoice is finalized, this field will equal customer.address. Once the invoice is finalized, this field will no longer be updated.

city

string

optional

City, district, suburb, town, or village.

country

string

optional

Two-letter country code (ISO 3166-1 alpha-2 ).

line1

string

optional

Address line 1 (e.g., street, PO Box, or company name).

line2

string

optional

Address line 2 (e.g., apartment, suite, unit, or building).

postal_code

string

optional

ZIP or postal code.

state

string

optional

State, county, province, or region.

customer_email

string

optional

The customer’s email. Until the invoice is finalized, this field will equal customer.email. Once the invoice is finalized, this field will no longer be updated.

customer_name

string

optional

The customer’s name. Until the invoice is finalized, this field will equal customer.name. Once the invoice is finalized, this field will no longer be updated.

customer_phone

string

optional

The customer’s phone number. Until the invoice is finalized, this field will equal customer.phone. Once the invoice is finalized, this field will no longer be updated.

customer_shipping

object

optional

address

object

optional

name

string

optional

phone

string

optional

default_payment_method

string

optional

ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription’s default payment method, if any, or to the default payment method in the customer’s invoice settings

due_date

string

optional

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

effective_at

string

optional

The date when this invoice is in effect. Same as finalized_at unless overwritten. When defined, this value replaces the system-generated ‘Date of issue’ printed on the invoice PDF and receipt.

footer

string

optional

Footer displayed on the invoice.

from_invoice

object

optional

action

string

required

The relation between the new invoice and the original invoice. Currently, only ‘revision’ is permitted

invoice

string

required

The id of the invoice that will be cloned.

invoice_pdf

string

optional

last_finalization_error

object

optional

The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.

type

string

optional

code

string

optional

message

string

optional

param

string

optional

If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field.

payment_method_type

string

optional

If the error is specific to the type of payment method, the payment method type that had a problem. This field is only populated for invoice-related errors.

latest_revision

string

optional

The ID of the most recent non-draft revision of this invoice

livemode

boolean

optional

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

next_payment_attempt

string

optional

The time at which payment will next be attempted. This value will be null for invoices where collection_method=send_invoice.

number

string

optional

A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer’s unique invoice_prefix if it is specified.

paid

boolean

optional

Whether payment was successfully collected for this invoice.

paid_out_of_band

boolean

optional

Returns true if the invoice was manually marked paid, returns false if the invoice hasn’t been paid yet or was paid on Wooshpay.

payment_settings

object

optional

default_mandate

string

optional

ID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the invoice’s default_payment_method or default_source, if set.

payment_method_options

object

optional

Payment-method-specific configuration to provide to the invoice’s PaymentIntent.

payment_method_types

string

optional

The list of payment method types (e.g. card) to provide to the invoice’s PaymentIntent.

receipt_number

string

optional

This is the transaction number that appears on email receipts sent for this invoice.

starting_balance

string

optional

Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.

statement_descriptor

string

optional

Extra information about an invoice for the customer’s credit card statement.

status_transitions

object

optional

The timestamps at which the invoice status was updated

finalized_at

string

optional

timestamp

marked_uncollectible_at

string

optional

timestamp

paid_at

string

optional

timestamp

voided_at

string

optional

timestamp

subscription_details

object

optional

Details about the subscription that created this invoice.

metadata

object

optional

test_clock

string

optional

ID of the test clock this invoice belongs to.

threshold_reason

object

optional

If billing_reason is set to subscription_threshold this returns more information on which threshold rules triggered the invoice.

amount_gte

string

optional

item_reasons

array [object {2}]

optional

total

integer

optional

Total after discounts and taxes.

rounding_rule

enum<string>

optional

If amount_precision is defined, this field is used to control rounding of the amount to the smallest unit supported by the currency.

Allowed values:

round_upround_down

Example

{
  "id": "string",
  "currency": "string",
  "customer": "string",
  "object": "string",
  "auto_advance": true,
  "charge": "string",
  "collection_method": "string",
  "description": "string",
  "hosted_invoice_url": "string",
  "lines": {
    "object": "string",
    "data": [
      {
        "id": "string",
        "object": "string",
        "amount": 0,
        "currency": "string",
        "description": "string",
        "metadata": {},
        "period": {
          "end": "string",
          "start": "string"
        },
        "price": {
          "id": "string",
          "object": "string",
          "active": true,
          "billing_scheme": "per_unit",
          "created": 0,
          "currency": "string",
          "livemode": true,
          "lookup_key": "string",
          "metadata": {},
          "nickname": "string",
          "product": "string",
          "type": "one_time",
          "unit_amount": 0,
          "recurring": {
            "interval": "day",
            "interval_count": 0,
            "usage_type": "licensed"
          },
          "tiers": [
            {
              "up_to": "string",
              "flat_amount": "string",
              "unit_amount": "string"
            }
          ]
        },
        "unit_amount": "string",
        "quantity": 0,
        "invoice_item": "string",
        "type": "string",
        "livemode": true,
        "subscription": "string",
        "subscription_item": "string",
        "unit_amount_excluding_tax": 0,
        "discount_amounts": [
          {
            "amount": "string",
            "discount": "string"
          }
        ],
        "discountable": true
      }
    ],
    "has_more": true,
    "url": "string"
  },
  "metadata": {},
  "payment_intent": "string",
  "period_end": "string",
  "period_start": "string",
  "status": "string",
  "subscription": "string",
  "account_country": "string",
  "account_name": "string",
  "amount_due": 0,
  "amount_paid": 0,
  "amount_precision": 0,
  "billing_reason": "manual",
  "created": 0,
  "custom_fields": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "customer_address": {
    "city": "string",
    "country": "string",
    "line1": "string",
    "line2": "string",
    "postal_code": "string",
    "state": "string"
  },
  "customer_email": "string",
  "customer_name": "string",
  "customer_phone": "string",
  "customer_shipping": {
    "address": {
      "city": "string",
      "country": "string",
      "line1": "string",
      "line2": "string",
      "postal_code": "string",
      "state": "string"
    },
    "name": "string",
    "phone": "string"
  },
  "default_payment_method": "string",
  "due_date": "string",
  "effective_at": "string",
  "footer": "string",
  "from_invoice": {
    "action": "string",
    "invoice": "string"
  },
  "invoice_pdf": "string",
  "last_finalization_error": {
    "type": "string",
    "code": "string",
    "message": "string",
    "param": "string",
    "payment_method_type": "string"
  },
  "latest_revision": "string",
  "livemode": true,
  "next_payment_attempt": "string",
  "number": "string",
  "paid": true,
  "paid_out_of_band": true,
  "payment_settings": {
    "default_mandate": "string",
    "payment_method_options": {
      "card": {
        "request_three_d_secure": "string"
      }
    },
    "payment_method_types": "string"
  },
  "receipt_number": "string",
  "starting_balance": "string",
  "statement_descriptor": "string",
  "status_transitions": {
    "finalized_at": "string",
    "marked_uncollectible_at": "string",
    "paid_at": "string",
    "voided_at": "string"
  },
  "subscription_details": {
    "metadata": {}
  },
  "test_clock": "string",
  "threshold_reason": {
    "amount_gte": "string",
    "item_reasons": [
      {
        "line_item_ids": "string",
        "usage_gte": "string"
      }
    ]
  },
  "total": 0,
  "rounding_rule": "round_up"
}

Modified at 2024-12-30 08:18:40

Retrieve an invoice

Send an invoice for manual payment