List all invoices

You can list all invoices, or list the invoices for a specific customer. The invoices are returned sorted by creation date, with the most recently created invoices appearing first.

Parameters

customerstring
Only return invoices for the customer specified by this customer ID.

statusenum
The status of the invoice, one of draft, open, paid, uncollectible, or void. Learn more

subscriptionstring
Only return invoices for the subscription specified by this subscription ID.

More parameters

collection_methodenum

createdobject

ending_beforestring

limitinteger

starting_afterstring

Returns

A dictionary with a data property that contains an array invoice attachments,

GET /v1/invoices

curl -G https://api.stripe.com/v1/invoices \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d limit=3

Response

{
  "object": "list",
  "url": "/v1/invoices",
  "has_more": false,
  "data": [
    {
      "id": "in_1MtHbELkdIwHu7ixl4OzzPMv",
      "object": "invoice",
      "account_country": "US",
      "account_name": "Stripe Docs",
      "account_tax_ids": null,
      "amount_due": 0,
      "amount_paid": 0,
      "amount_overpaid": 0,
      "amount_remaining": 0,
      "amount_shipping": 0,
      "application": null,
      "attempt_count": 0,
      "attempted": false,
      "auto_advance": false,
      "automatic_tax": {
        "enabled": false,
        "liability": null,
        "status": null
      },
      "billing_reason": "manual",
      "collection_method": "charge_automatically",
      "created": 1680644467,
      "currency": "usd",
      "custom_fields": null,
      "customer": "cus_NeZwdNtLEOXuvB",
      "customer_address": null,
      "customer_email": "jennyrosen@example.com",
      "customer_name": "Jenny Rosen",
      "customer_phone": null,
      "customer_shipping": null,
      "customer_tax_exempt": "none",
      "customer_tax_ids": [],
      "default_payment_method": null,
      "default_source": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "due_date": null,
      "ending_balance": null,
      "footer": null,
      "from_invoice": null,
      "hosted_invoice_url": null,
      "invoice_pdf": null,
      "issuer": {
        "type": "self"
      },
      "last_finalization_error": null,
      "latest_revision": null,
      "lines": {
        "object": "list",
        "data": [],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines"
      },
      "livemode": false,
      "metadata": {},
      "next_payment_attempt": null,
      "number": null,
      "on_behalf_of": null,
      "parent": null,
      "payment_settings": {
        "default_mandate": null,
        "payment_method_options": null,
        "payment_method_types": null
      },
      "period_end": 1680644467,
      "period_start": 1680644467,
      "post_payment_credit_notes_amount": 0,
      "pre_payment_credit_notes_amount": 0,
      "receipt_number": null,
      "shipping_cost": null,
      "shipping_details": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "status": "draft",
      "status_transitions": {
        "finalized_at": null,
        "marked_uncollectible_at": null,
        "paid_at": null,
        "voided_at": null
      },
      "subtotal": 0,
      "subtotal_excluding_tax": 0,
      "test_clock": null,
      "total": 0,
      "total_discount_amounts": [],
      "total_excluding_tax": 0,
      "total_taxes": [],
      "webhooks_delivered_at": 1680644467
    }
  ]
}

Delete a draft invoice

Permanently deletes a one-off invoice draft. This cannot be undone. Attempts to delete invoices that are no longer in a draft state will fail; once an invoice has been finalized or if an invoice is for a subscription, it must be voided.

Parameters

No parameters.

Returns

A successfully deleted invoice. Otherwise, this call raises an error, such as if the invoice has already been deleted.

DELETE /v1/invoices/:id

curl -X DELETE https://api.stripe.com/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"

Response

{
  "id": "in_1MtHbELkdIwHu7ixl4OzzPMv",
  "object": "invoice",
  "deleted": true
}

Attach a payment to an Invoice

Attaches a PaymentIntent or an Out of Band Payment to the invoice, adding it to the list of payments.

For the PaymentIntent, when the PaymentIntent’s status changes to succeeded, the payment is credited to the invoice, increasing its amount_paid. When the invoice is fully paid, the invoice’s status becomes paid.

If the PaymentIntent’s status is already succeeded when it’s attached, it’s credited to the invoice immediately.

See: Partial payments to learn more.

Parameters

payment_intentstring
The ID of the PaymentIntent to attach to the invoice.

payment_recordstring
The ID of the PaymentRecord to attach to the invoice.

Returns

Returns the invoice object that the payment was attached to.

POST /v1/invoices/:id/attach_payment

curl https://api.stripe.com/v1/invoices/in_1Nj68C2eZvKYlo2CGmFJak8q/attach_payment \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d payment_intent=pi_1GszwY2eZvKYlo2CohCEmT6b \
  -d "expand[]"=payments

Response

{
  "id": "in_1Nj68C2eZvKYlo2CGmFJak8q",
  "object": "invoice",
  "account_country": "US",
  "account_name": "Stripe.com",
  "account_tax_ids": null,
  "amount_due": 1299,
  "amount_paid": 0,
  "amount_overpaid": 0,
  "amount_remaining": 1299,
  "amount_shipping": 0,
  "application": null,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "automatic_tax": {
    "enabled": false,
    "liability": null,
    "status": null
  },
  "billing_reason": "manual",
  "collection_method": "charge_automatically",
  "created": 1692993440,
  "currency": "usd",
  "custom_fields": null,
  "customer": "cus_9s6XKzkNRiz8i3",
  "customer_address": null,
  "customer_email": "test@test.com",
  "customer_name": null,
  "customer_phone": null,
  "customer_shipping": null,
  "customer_tax_exempt": "none",
  "customer_tax_ids": [],
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "due_date": null,
  "effective_at": null,
  "ending_balance": null,
  "footer": null,
  "from_invoice": null,
  "hosted_invoice_url": null,
  "invoice_pdf": null,
  "issuer": {
    "type": "self"
  },
  "last_finalization_error": null,
  "latest_revision": null,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "il_1Nj68C2eZvKYlo2C7fRlh2gN",
        "object": "line_item",
        "amount": 1299,
        "currency": "usd",
        "description": "My First Invoice Item (created for API docs)",
        "discount_amounts": [],
        "discountable": true,
        "discounts": [],
        "livemode": false,
        "metadata": {},
        "parent": {
          "type": "invoice_item_details",
          "invoice_item_details": {
            "invoice_item": "ii_1Nj68C2eZvKYlo2CTeCUHDgE",
            "proration": false,
            "proration_details": {
              "credited_items": null
            },
            "subscription": null
          }
        },
        "period": {
          "end": 1692993440,
          "start": 1692993440
        },
        "pricing": {
          "price_details": {
            "price": "price_1Nj5c82eZvKYlo2CfVgOGez4",
            "product": "prod_OW7r6RmADUSO13"
          },
          "type": "price_details",
          "unit_amount_decimal": "1299"
        },
        "quantity": 1,
        "taxes": []
      }
    ],
    "has_more": false,
    "url": "/v1/invoices/in_1Nj68C2eZvKYlo2CGmFJak8q/lines"
  },
  "livemode": false,
  "metadata": {},
  "next_payment_attempt": null,
  "number": null,
  "on_behalf_of": null,
  "parent": null,
  "payment_settings": {
    "default_mandate": null,
    "payment_method_options": null,
    "payment_method_types": null
  },
  "payments": {
    "object": "list",
    "data": [
      {
        "id": "inpay_1M3USa2eZvKYlo2CBjuwbq0N",
        "object": "invoice_payment",
        "amount_paid": 2000,
        "amount_requested": 2000,
        "created": 1391288554,
        "currency": "usd",
        "invoice": "in_1Nj68C2eZvKYlo2CGmFJak8q",
        "is_default": true,
        "livemode": false,
        "payment": {
          "type": "payment_intent",
          "payment_intent": "pi_1GszwY2eZvKYlo2CohCEmT6b"
        },
        "status": "paid",
        "status_transitions": {
          "canceled_at": null,
          "paid_at": 1391288554
        }
      }
    ],
    "has_more": false,
    "url": "/v1/invoices/in_1Nj68C2eZvKYlo2CGmFJak8q/payments"
  },
  "period_end": 1688482163,
  "period_start": 1688395763,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "receipt_number": null,
  "redaction": null,
  "shipping_cost": null,
  "shipping_details": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "status": "open",
  "status_transitions": {
    "finalized_at": null,
    "marked_uncollectible_at": null,
    "paid_at": null,
    "voided_at": null
  },
  "subtotal": 1299,
  "subtotal_excluding_tax": 1299,
  "test_clock": null,
  "total": 1299,
  "total_discount_amounts": [],
  "total_excluding_tax": 1299,
  "total_taxes": [],
  "transfer_data": null,
  "webhooks_delivered_at": null
}

Finalize an invoice

Stripe 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.

Parameters

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

Returns

Returns an invoice object with status=open.

POST /v1/invoices/:id/finalize

curl -X POST https://api.stripe.com/v1/invoices/in_1MtGmCLkdIwHu7ix6PgS6g8S/finalize \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"

Response

{
  "id": "in_1MtGmCLkdIwHu7ix6PgS6g8S",
  "object": "invoice",
  "account_country": "US",
  "account_name": "Stripe Docs",
  "account_tax_ids": null,
  "amount_due": 0,
  "amount_paid": 0,
  "amount_overpaid": 0,
  "amount_remaining": 0,
  "amount_shipping": 0,
  "application": null,
  "attempt_count": 0,
  "attempted": true,
  "auto_advance": false,
  "automatic_tax": {
    "enabled": false,
    "liability": null,
    "status": null
  },
  "billing_reason": "manual",
  "collection_method": "send_invoice",
  "created": 1680641304,
  "currency": "usd",
  "custom_fields": null,
  "customer": "cus_NeZw0zvTyquTfF",
  "customer_address": null,
  "customer_email": "jennyrosen@example.com",
  "customer_name": "Jenny Rosen",
  "customer_phone": null,
  "customer_shipping": null,
  "customer_tax_exempt": "none",
  "customer_tax_ids": [],
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "due_date": 1681246104,
  "ending_balance": 0,
  "footer": null,
  "from_invoice": null,
  "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9OZVp3dVBYNnF0dGlvdXRubGVjSXVOOWhiVWpmUktPLDcxMTgyMTA10200x7P2wMSm?s=ap",
  "invoice_pdf": "https://pay.stripe.com/invoice/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9OZVp3dVBYNnF0dGlvdXRubGVjSXVOOWhiVWpmUktPLDcxMTgyMTA10200x7P2wMSm/pdf?s=ap",
  "issuer": {
    "type": "self"
  },
  "last_finalization_error": null,
  "latest_revision": null,
  "lines": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/invoices/in_1MtGmCLkdIwHu7ix6PgS6g8S/lines"
  },
  "livemode": false,
  "metadata": {},
  "next_payment_attempt": null,
  "number": "9545A614-0001",
  "on_behalf_of": null,
  "parent": null,
  "payment_settings": {
    "default_mandate": null,
    "payment_method_options": null,
    "payment_method_types": null
  },
  "period_end": 1680641304,
  "period_start": 1680641304,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "receipt_number": null,
  "shipping_cost": null,
  "shipping_details": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "status": "paid",
  "status_transitions": {
    "finalized_at": 1680641304,
    "marked_uncollectible_at": null,
    "paid_at": 1680641304,
    "voided_at": null
  },
  "subtotal": 0,
  "subtotal_excluding_tax": 0,
  "test_clock": null,
  "total": 0,
  "total_discount_amounts": [],
  "total_excluding_tax": 0,
  "total_taxes": [],
  "webhooks_delivered_at": 1680641304
}

Mark an invoice as uncollectible

Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes.

Parameters

No parameters.

Returns

Returns the invoice object.

POST /v1/invoices/:id/mark_uncollectible

curl -X POST https://api.stripe.com/v1/invoices/in_1MtG0nLkdIwHu7ixAaUw3Cb4/mark_uncollectible \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"

Response

{
  "id": "in_1MtG0nLkdIwHu7ixAaUw3Cb4",
  "object": "invoice",
  "account_country": "US",
  "account_name": "Stripe Docs",
  "account_tax_ids": null,
  "amount_due": 599,
  "amount_paid": 0,
  "amount_overpaid": 0,
  "amount_remaining": 599,
  "amount_shipping": 0,
  "application": null,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "automatic_tax": {
    "enabled": false,
    "liability": null,
    "status": null
  },
  "billing_reason": "manual",
  "collection_method": "charge_automatically",
  "created": 1680638365,
  "currency": "usd",
  "custom_fields": null,
  "customer": "cus_NeZw0zvTyquTfF",
  "customer_address": null,
  "customer_email": "jennyrosen@example.com",
  "customer_name": "Jenny Rosen",
  "customer_phone": null,
  "customer_shipping": null,
  "customer_tax_exempt": "none",
  "customer_tax_ids": [
    {
      "type": "eu_vat",
      "value": "DE123456789"
    },
    {
      "type": "eu_vat",
      "value": "DE123456781"
    }
  ],
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "due_date": null,
  "ending_balance": null,
  "footer": null,
  "from_invoice": null,
  "hosted_invoice_url": null,
  "invoice_pdf": null,
  "issuer": {
    "type": "self"
  },
  "last_finalization_error": null,
  "latest_revision": null,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "il_1MtG0nLkdIwHu7ix3eCoIIw7",
        "object": "line_item",
        "amount": 1099,
        "currency": "usd",
        "description": "My First Invoice Item (created for API docs)",
        "discount_amounts": [],
        "discountable": true,
        "discounts": [],
        "livemode": false,
        "metadata": {},
        "parent": {
          "type": "invoice_item_details",
          "invoice_item_details": {
            "invoice_item": "ii_1MtG0nLkdIwHu7ixDqfiUgg8",
            "proration": false,
            "proration_details": {
              "credited_items": null
            },
            "subscription": null
          }
        },
        "period": {
          "end": 1680638365,
          "start": 1680638365
        },
        "pricing": {
          "price_details": {
            "price": "price_1Mr89PLkdIwHu7ixf5QhiWm2",
            "product": "prod_NcMtLgctyqlJDC"
          },
          "type": "price_details",
          "unit_amount_decimal": "1099"
        },
        "quantity": 1,
        "taxes": []
      }
    ],
    "has_more": false,
    "url": "/v1/invoices/in_1MtG0nLkdIwHu7ixAaUw3Cb4/lines"
  },
  "livemode": false,
  "metadata": {},
  "next_payment_attempt": null,
  "number": null,
  "on_behalf_of": null,
  "parent": null,
  "payment_settings": {
    "default_mandate": null,
    "payment_method_options": null,
    "payment_method_types": null
  },
  "period_end": 1680638365,
  "period_start": 1680638365,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "receipt_number": null,
  "shipping_cost": null,
  "shipping_details": null,
  "starting_balance": -500,
  "statement_descriptor": null,
  "status": "uncollectible",
  "status_transitions": {
    "finalized_at": null,
    "marked_uncollectible_at": null,
    "paid_at": null,
    "voided_at": null
  },
  "subtotal": 1099,
  "subtotal_excluding_tax": 1099,
  "test_clock": null,
  "total": 1099,
  "total_discount_amounts": [],
  "total_excluding_tax": 1099,
  "total_taxes": [],
  "webhooks_delivered_at": null,
  "closed": true,
  "forgiven": true
}

List all invoices

Parameters

customerstring

statusenum

subscriptionstring

More parametersExpand all

collection_methodenum

createdobject

ending_beforestring

limitinteger

starting_afterstring

Returns

Delete a draft invoice

Parameters

Returns

Attach a payment to an Invoice

Parameters

payment_intentstring

payment_recordstring

Returns

Finalize an invoice

Parameters

auto_advanceboolean

Returns

Mark an invoice as uncollectible

Parameters

Returns

More parameters