---
title: "Mark invoice unpaid"
description: "Reverts a paid mark: sets the invoice financial status back to pending and clears the paid-at time, the same field edit the invoice editor saves. Shopify is not told."
url: https://docs.invoicefalcon.com/v3-reference/documents/mark-invoice-unpaid/
api: "API v3 reference"
method: POST
path: "/documents/invoices/{id}/mark_unpaid"
---

# Mark invoice unpaid

`POST https://app.invoicefalcon.com/api/v3/external/documents/invoices/{id}/mark_unpaid`

Reverts a paid mark: sets the invoice financial status back to pending and clears the paid-at time, the same field edit the invoice editor saves. Shopify is not told.

**Note:** Changes the invoice document only; payment reminders resume if enabled. Calling it on an invoice that is not marked paid changes nothing and returns the invoice as it is.

## Path parameters

- `id` (string, required)

## Returns

- `id` (integer): e.g. `980191007`
- `document_type` (string): e.g. `invoice`
- `invoice_number` (string): e.g. `#1001`
- `title` (string): e.g. `Invoice`
- `order` (object)
  - `shopify_order_id` (string): e.g. `gid://shopify/Order/12213474623569`
  - `name` (string): e.g. `#1001`
  - `number` (integer): e.g. `1001`
- `customer` (object)
  - `id` (integer): e.g. `25`
  - `name` (string): e.g. `Customer 1`
  - `email` (string): e.g. `cus1@gmail.com`
  - `shopify_customer_id` (string): e.g. `gid://shopify/Customer/23935678808145`
  - `phone` (string, nullable)
  - `tax_number` (string, nullable)
  - `eori_number` (string, nullable)
  - `tags` (array of anys)
- `financial_status` (string): e.g. `pending`
- `currency` (string): e.g. `USD`
- `total` (string): e.g. `1100.22`
- `issued_on` (string): e.g. `2025-12-11`
- `due_on` (string, nullable)
- `sent_at` (string, nullable)
- `printed_at` (string, nullable)
- `reminder_sent_at` (string, nullable)
- `paid` (boolean): e.g. `false`
- `edited` (boolean): e.g. `true`
- `trashed` (boolean): e.g. `false`
- `e_invoice_status` (string, nullable)
- `created_at` (string): e.g. `2026-11-10T08:35:22Z`
- `fulfillment_status` (string, nullable)
- `dates` (object)
  - `order_placed_at` (string): e.g. `2025-12-11T00:00:00Z`
  - `issued_on` (string): e.g. `2025-12-11`
  - `due_on` (string, nullable)
  - `tax_date` (string, nullable)
  - `fulfilled_on` (string, nullable)
- `po_number` (string, nullable)
- `payment_terms` (string, nullable)
- `payment_gateway` (string): e.g. `manual`
- `locale` (string): e.g. `en`
- `totals` (object)
  - `currency` (string): e.g. `USD`
  - `taxes_included` (boolean): e.g. `false`
  - `subtotal` (string): e.g. `1497.95`
  - `discounts` (string): e.g. `494.32`
  - `shipping` (string): e.g. `6.90`
  - `tax` (string): e.g. `89.69`
  - `duties` (string): e.g. `0.00`
  - `total` (string): e.g. `1100.22`
  - `total_paid` (string): e.g. `0.00`
  - `total_refunded` (string): e.g. `0.00`
  - `total_due` (string): e.g. `0.00`
- `billing_address` (object)
  - `name` (string): e.g. `Customer 1`
  - `first_name` (string): e.g. `Customer`
  - `last_name` (string): e.g. `1`
  - `company` (string, nullable)
  - `address1` (string, nullable)
  - `address2` (string, nullable)
  - `city` (string, nullable)
  - `province` (string, nullable)
  - `zip` (string, nullable)
  - `country` (string): e.g. `United States`
  - `country_code` (string): e.g. `US`
  - `phone` (string, nullable)
  - `tax_number` (string, nullable)
  - `eori_number` (string, nullable)
- `shipping_address` (object)
  - `name` (string): e.g. `Customer 1`
  - `first_name` (string): e.g. `Customer`
  - `last_name` (string): e.g. `1`
  - `company` (string, nullable)
  - `address1` (string): e.g. `New York`
  - `address2` (string, nullable)
  - `city` (string): e.g. `New York`
  - `province` (string): e.g. `New York`
  - `zip` (string): e.g. `10004`
  - `country` (string): e.g. `United States`
  - `country_code` (string): e.g. `US`
  - `phone` (string, nullable)
  - `tax_number` (string, nullable)
  - `eori_number` (string, nullable)
- `line_items` (array of objects)
  - `id` (integer): e.g. `536`
  - `title` (string): e.g. `The Videographer Snowboard`
  - `variant_title` (string, nullable)
  - `sku` (string): e.g. `9506.11.21`
  - `barcode` (string, nullable)
  - `product_type` (string, nullable)
  - `quantity` (integer): e.g. `1`
  - `unit_price` (string): e.g. `885.95`
  - `discount` (string): e.g. `0.00`
  - `discounted_unit_price` (string): e.g. `885.95`
  - `total_discount` (string): e.g. `0.00`
  - `tax` (string): e.g. `78.63`
  - `tax_lines` (array of objects)
    - `title` (string): e.g. `New York State Tax`
    - `rate` (string): e.g. `4.0`
  - `total` (string): e.g. `885.95`
  - `refunded_quantity` (integer): e.g. `0`
  - `image_url` (string, nullable)
  - `properties` (array of anys)
  - `note` (string, nullable)
- `shipping_lines` (array of objects)
  - `title` (string): e.g. `Standard`
  - `price` (string): e.g. `6.90`
  - `discount` (string): e.g. `0.00`
  - `tax` (string): e.g. `0.62`
  - `tax_lines` (array of objects)
    - `title` (string): e.g. `New York State Tax`
    - `rate` (string): e.g. `4.0`
    - `amount` (string): e.g. `0.28`
- `tax_lines` (array of objects)
  - `title` (string): e.g. `New York State Tax`
  - `rate` (string): e.g. `4.0`
  - `amount` (string): e.g. `40.42`
- `discount_codes` (array of strings)
- `notes` (object)
  - `note` (string, nullable)
  - `custom_note` (string, nullable)
  - `note_attributes` (array of anys)
- `custom_fields` (array of anys)
- `tags` (array of anys)
- `tracking` (object)
  - `companies` (array of anys, nullable)
  - `numbers` (array of anys, nullable)
- `pdf` (object)
  - `available` (boolean): e.g. `false`
  - `filename` (string, nullable)
  - `url` (string, nullable)
  - `generated_at` (string, nullable)
- `e_invoice` (object)
  - `status` (object, nullable)
  - `requested` (boolean): e.g. `false`
  - `error` (string, nullable)
- `updated_at` (string): e.g. `2026-11-10T08:35:22Z`

Rate limit: this call costs 2 points ([rate limits](https://docs.invoicefalcon.com/v3/docs/api-v3/rate-limits/)).

## Example request

```sh
curl -X POST "https://app.invoicefalcon.com/api/v3/external/documents/invoices/980191059/mark_unpaid" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

The updated resource.

```json
{
  "id": 980191007,
  "document_type": "invoice",
  "invoice_number": "#1001",
  "title": "Invoice",
  "order": {
    "shopify_order_id": "gid://shopify/Order/12213474623569",
    "name": "#1001",
    "number": 1001
  },
  "customer": {
    "id": 25,
    "name": "Customer 1",
    "email": "cus1@gmail.com",
    "shopify_customer_id": "gid://shopify/Customer/23935678808145",
    "phone": null,
    "tax_number": null,
    "eori_number": null,
    "tags": []
  },
  "financial_status": "pending",
  "currency": "USD",
  "total": "1100.22",
  "issued_on": "2025-12-11",
  "due_on": null,
  "sent_at": null,
  "printed_at": null,
  "reminder_sent_at": null,
  "paid": false,
  "edited": true,
  "trashed": false,
  "e_invoice_status": null,
  "created_at": "2026-11-10T08:35:22Z",
  "fulfillment_status": null,
  "dates": {
    "order_placed_at": "2025-12-11T00:00:00Z",
    "issued_on": "2025-12-11",
    "due_on": null,
    "tax_date": null,
    "fulfilled_on": null
  },
  "po_number": null,
  "payment_terms": null,
  "payment_gateway": "manual",
  "locale": "en",
  "totals": {
    "currency": "USD",
    "taxes_included": false,
    "subtotal": "1497.95",
    "discounts": "494.32",
    "shipping": "6.90",
    "tax": "89.69",
    "duties": "0.00",
    "total": "1100.22",
    "total_paid": "0.00",
    "total_refunded": "0.00",
    "total_due": "0.00"
  },
  "billing_address": {
    "name": "Customer 1",
    "first_name": "Customer",
    "last_name": "1",
    "company": null,
    "address1": null,
    "address2": null,
    "city": null,
    "province": null,
    "zip": null,
    "country": "United States",
    "country_code": "US",
    "phone": null,
    "tax_number": null,
    "eori_number": null
  },
  "shipping_address": {
    "name": "Customer 1",
    "first_name": "Customer",
    "last_name": "1",
    "company": null,
    "address1": "New York",
    "address2": null,
    "city": "New York",
    "province": "New York",
    "zip": "10004",
    "country": "United States",
    "country_code": "US",
    "phone": null,
    "tax_number": null,
    "eori_number": null
  },
  "line_items": [
    {
      "id": 536,
      "title": "The Videographer Snowboard",
      "variant_title": null,
      "sku": "9506.11.21",
      "barcode": null,
      "product_type": null,
      "quantity": 1,
      "unit_price": "885.95",
      "discount": "0.00",
      "discounted_unit_price": "885.95",
      "total_discount": "0.00",
      "tax": "78.63",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375"
        }
      ],
      "total": "885.95",
      "refunded_quantity": 0,
      "image_url": null,
      "properties": [],
      "note": null
    },
    {
      "id": 537,
      "title": "Custom 1",
      "variant_title": null,
      "sku": null,
      "barcode": null,
      "product_type": null,
      "quantity": 1,
      "unit_price": "12.00",
      "discount": "0.00",
      "discounted_unit_price": "12.00",
      "total_discount": "0.00",
      "tax": "1.07",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375"
        }
      ],
      "total": "12.00",
      "refunded_quantity": 0,
      "image_url": null,
      "properties": [],
      "note": null
    },
    {
      "id": 538,
      "title": "The Collection Snowboard: Hydrogen",
      "variant_title": null,
      "sku": "9506.11.21",
      "barcode": null,
      "product_type": null,
      "quantity": 1,
      "unit_price": "600.00",
      "discount": "0.00",
      "discounted_unit_price": "600.00",
      "total_discount": "0.00",
      "tax": "53.25",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375"
        }
      ],
      "total": "600.00",
      "refunded_quantity": 0,
      "image_url": null,
      "properties": [],
      "note": null
    }
  ],
  "shipping_lines": [
    {
      "title": "Standard",
      "price": "6.90",
      "discount": "0.00",
      "tax": "0.62",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0",
          "amount": "0.28"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5",
          "amount": "0.31"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375",
          "amount": "0.03"
        }
      ]
    }
  ],
  "tax_lines": [
    {
      "title": "New York State Tax",
      "rate": "4.0",
      "amount": "40.42"
    },
    {
      "title": "New York City City Tax",
      "rate": "4.5",
      "amount": "45.47"
    },
    {
      "title": "Metropolitan Commuter Transportation District",
      "rate": "0.375",
      "amount": "3.80"
    }
  ],
  "discount_codes": [
    "Order discount in percentage"
  ],
  "notes": {
    "note": null,
    "custom_note": null,
    "note_attributes": []
  },
  "custom_fields": [],
  "tags": [],
  "tracking": {
    "companies": null,
    "numbers": null
  },
  "pdf": {
    "available": false,
    "filename": null,
    "url": null,
    "generated_at": null
  },
  "e_invoice": {
    "status": null,
    "requested": false,
    "error": null
  },
  "updated_at": "2026-11-10T08:35:22Z"
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 404

The resource does not exist for this shop, or no action is registered at this path.

```json
{
  "errors": [
    "Resource not found"
  ],
  "code": "not_found"
}
```

## 409

The request conflicts with the current state (an issued invoice is locked, the next invoice number moved, a template is still in use, a job already finished). Nothing was changed.

```json
{
  "errors": [
    "This shop keeps issued invoices unchanged, so this invoice cannot be edited."
  ],
  "code": "invoice_locked"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

