Sign in

v8

OpenAPI 3.1.02026-08-033623795.0 MB
Invoices

Update invoice

Update a draft invoice's details.

Required permissions:

  • invoice:update
  • member:email:read
patch/invoices/{id}

Path parameters

idstring required
Example:inv_xxxxxxxxxxxxxx

The unique identifier of the invoice to update.

Request body

automatically_finalizes_atstring date-time nullable

The date and time when the invoice will be automatically finalized. For charge_automatically, triggers an automatic charge. For send_invoice, sends the invoice email at the specified time.

charge_buyer_feeboolean nullable

Whether to charge the customer a buyer fee on this invoice.

collection_method'send_invoice' | 'charge_automatically'

The method of collection for an invoice.

customer_namestring nullable

The name of the customer.

due_datestring date-time nullable

The date by which the invoice must be paid.

email_addressstring nullable

The email address of the customer.

mailing_address_idstring nullable

The unique identifier of an existing mailing address to attach.

member_idstring nullable

The unique identifier of a member to assign as the customer.

payment_method_idstring nullable

The unique identifier of the payment method to charge.

product_idstring nullable

The unique identifier of an existing product to attach to this invoice. Only allowed while the invoice is still a draft.

subscription_billing_anchor_atstring date-time nullable

The date that defines when the subscription billing cycle should start.

Example request

{
  "automatically_finalizes_at": "2023-12-01T05:00:00.401Z",
  "due_date": "2023-12-01T05:00:00.401Z",
  "line_items": [
    {
      "quantity": 6.9,
      "unit_price": 6.9
    }
  ],
  "mailing_address_id": "ma_xxxxxxxxxxxxxxx",
  "member_id": "mber_xxxxxxxxxxxxx",
  "payment_method_id": "pmt_xxxxxxxxxxxxxx",
  "plan": {
    "billing_period": 42,
    "custom_fields": [
      {
        "order": 42
      }
    ],
    "expiration_days": 42,
    "initial_price": 6.9,
    "renewal_price": 6.9,
    "stock": 42,
    "trial_period_days": 42
  },
  "product_id": "prod_xxxxxxxxxxxxx",
  "subscription_billing_anchor_at": "2023-12-01T05:00:00.401Z"
}

Response

A successful response

automatically_finalizes_atstring date-time nullable required

The date and time when the invoice will be automatically finalized. For charge_automatically, triggers an automatic charge. For send_invoice, sends the invoice email at the specified time.

charge_buyer_feeboolean required

Whether the invoice includes a buyer processing fee on top of the plan price.

collection_method'send_invoice' | 'charge_automatically' required

The method of collection for an invoice.

created_atstring date-time required

The datetime the invoice was created.

customer_namestring nullable required

The full name of the customer this invoice is addressed to. Null if no name is on file.

due_datestring date-time nullable required

The deadline by which payment is expected. Null if the invoice is collected automatically.

email_addressstring nullable required

The email address of the customer this invoice is addressed to. Null if no email is on file.

fetch_invoice_tokenstring required

A signed token that allows fetching invoice data publicly without authentication.

idstring required

The unique identifier for the invoice.

numberstring required

The sequential invoice number for display purposes.

pay_online_urlstring nullable required

The checkout URL where the customer can pay this invoice online, with their email address pre-filled and locked.

status'draft' | 'open' | 'paid' | 'past_due' | 'uncollectible' | 'void' required

The different statuses an invoice can be in

subscription_billing_anchor_atstring date-time nullable required

The date that defines when the subscription billing cycle starts. When set on a renewal plan invoice, all future billing periods anchor to this date.

updated_atstring date-time required

The datetime the invoice was last updated.

Example response

{
  "automatically_finalizes_at": "2023-12-01T05:00:00.401Z",
  "company": {
    "id": "biz_xxxxxxxxxxxxxx"
  },
  "created_at": "2023-12-01T05:00:00.401Z",
  "current_plan": {
    "description": "Monthly access to all premium analytics dashboards and data exports.",
    "formatted_price": "$10.00",
    "id": "plan_xxxxxxxxxxxxx"
  },
  "customer_name": "Jane Doe",
  "due_date": "2023-12-01T05:00:00.401Z",
  "email_address": "customer@example.com",
  "fetch_invoice_token": "eyJhbGciOiJIUzI1NiJ9...",
  "id": "inv_xxxxxxxxxxxxxx",
  "line_items": [
    {
      "label": "Platform subscription",
      "position": 42,
      "quantity": 6.9,
      "total": 6.9,
      "unit_price": 6.9
    }
  ],
  "number": "#0001",
  "product": {
    "id": "prod_xxxxxxxxxxxxx",
    "title": "Pickaxe Analytics"
  },
  "subscription_billing_anchor_at": "2023-12-01T05:00:00.401Z",
  "updated_at": "2023-12-01T05:00:00.401Z",
  "user": {
    "email": "john.doe@example.com",
    "id": "user_xxxxxxxxxxxxx",
    "name": "John Doe",
    "username": "johndoe42"
  }
}