For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL. To search these docs, send a GET request to https://paddle-docs-retrieval.kapa-paddle.workers.dev/?q=<question> with a URL-encoded question. No authentication needed.

Skip to content
Paddle Docs home

Cancel an invoice

Cancel an invoice if you created it in error. Canceled invoices remain on your system for recordkeeping purposes.

AI summary

Cancel manually-collected invoices by updating their status to canceled, which removes the payment obligation and prevents checkout links from working.

  • •Only transactions with collection_mode: manual and status of draft, ready, billed, or past_due can be canceled via API; subscription-generated invoices require the dashboard
  • •Canceled invoices remain in your system for record-keeping but don't count as revenue, and cancellation is irreversible
  • •Use webhooks to build automated workflows that cancel related subscriptions when manually-collected transactions are canceled

If you've created an invoice in error, you can cancel it to say that it's no longer needed.

How it works

Invoices work using manually-collected transactions. These are transactions where the collection_mode is set to manual, which means that Paddle sends an invoice that customers must pay themselves by bank transfer or using Paddle Checkout.

You can change the status of a manually-collected transaction to canceled to mark it as canceled. When you cancel an invoice:

  • It's no longer due, so customers don't need to pay it
  • Links to pay the invoice using Paddle Checkout no longer work
  • It doesn't count as revenue for your reports
  • You can't uncancel it, or make any other changes to it

You can cancel manually-collected transactions that are draft, ready, billed (issued invoices), or past_due (overdue invoices). If a transaction is completed, meaning a customer has paid an invoice, you can create an adjustment to refund all or part of it instead.

Invoices that Paddle creates for a subscription, like renewal invoices or invoices for subscription changes and one-time charges, can only be canceled using the Paddle dashboard. Their origin starts with subscription_. If you try to cancel them using the API, Paddle returns a forbidden error.

Credit an invoice

You might be able to correct some errors on an issued invoice by creating a credit rather than canceling it.

For example, if you create and issue an invoice then want to remove an item, you can create an adjustment for the item you want to remove. Paddle automatically applies the credit to the issued invoice, so the amount the customer owes is reduced.

When you credit the full value of a transaction, it's marked as completed. It's no longer due.

Cancel an invoice

Send a PATCH request to the /transactions/{transaction_id} endpoint to update a manually-collected transaction, setting status to canceled in your request.

  1. Go to Paddle > Transactions.
  2. Use the search box and the Filter by drop-down to find a transaction you want to cancel.
  3. Click into the transaction, then click the menu and choose Cancel transaction
  4. Click Cancel transaction to confirm.

Set status to canceled in your request body. Don't include any other fields, or your request fails.

Transactions must be manually collected and draft, ready, billed, or past_due to cancel. You can't cancel invoices that Paddle created for a subscription using the API. Use list transactions with collection_mode=manual, origin=api,web, and status=draft,ready,billed,past_due to find transactions you can cancel using the API.

PATCH/transactions/{transaction_id}
Request
{
  "status": "canceled"
}
Response (200 OK)
{
  "data": {
    "id": "txn_01j5dx3yajy2hc1p1xz808m92j",
    "status": "canceled",
    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
    "address_id": "add_01hv8gq3318ktkfengj2r75gfx",
    "business_id": null,
    "custom_data": null,
    "origin": "api",
    "collection_mode": "manual",
    "subscription_id": null,
    "invoice_id": null,
    "invoice_number": null,
    "billing_details": {
      "enable_checkout": false,
      "payment_terms": {
        "interval": "day",
        "frequency": 14
      },
      "purchase_order_number": "PO-123",
      "additional_information": null
    },
    "billing_period": {
      "starts_at": "2024-04-12T00:00:00Z",
      "ends_at": "2025-04-11T23:59:00Z"
    },
    "currency_code": "USD",
    "discount_id": null,
    "created_at": "2024-08-16T15:32:53.640052Z",
    "updated_at": "2024-08-16T15:33:11.477353084Z",
    "billed_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "description": "Annual",
          "type": "standard",
          "name": "Annual (per seat)",
          "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "50000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "status": "active",
          "created_at": "2023-02-23T13:57:54.249913Z",
          "updated_at": "2024-04-05T14:32:00.471447Z"
        },
        "quantity": 20
      },
      {
        "price": {
          "id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
          "description": "Annual (recurring addon)",
          "type": "standard",
          "name": "Annual (recurring addon)",
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "300000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active",
          "created_at": "2023-02-23T14:00:40.265185Z",
          "updated_at": "2024-03-25T14:31:18.587603Z"
        },
        "quantity": 1
      },
      {
        "price": {
          "id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "description": "One-time addon",
          "type": "standard",
          "name": "One-time addon",
          "product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "billing_cycle": null,
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "19900",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active",
          "created_at": "2023-02-23T14:01:28.391712Z",
          "updated_at": "2024-04-09T07:23:10.921392Z"
        },
        "quantity": 1
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "1319900",
            "discount": "0",
            "tax": "117141",
            "total": "1437041"
          }
        }
      ],
      "totals": {
        "subtotal": "1319900",
        "tax": "117141",
        "discount": "0",
        "total": "1437041",
        "grand_total": "1437041",
        "fee": null,
        "credit": "0",
        "credit_to_balance": "0",
        "balance": "1437041",
        "earnings": null,
        "currency_code": "USD"
      },
      "adjusted_totals": {
        "subtotal": "1319900",
        "tax": "117141",
        "total": "1437041",
        "grand_total": "1437041",
        "fee": "0",
        "earnings": "0",
        "currency_code": "USD"
      },
      "payout_totals": null,
      "adjusted_payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01j5dx3yqvsgxtvrj6f0h6jw3t",
          "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "quantity": 20,
          "totals": {
            "subtotal": "1000000",
            "tax": "88750",
            "discount": "0",
            "total": "1088750"
          },
          "product": {
            "id": "pro_01gsz4vmqbjk3x4vvtafffd540",
            "name": "AeroEdit Enterprise",
            "description": "The ultimate solution for organizations, featuring all Pro capabilities plus multi-user support, advanced data storage capabilities, plus personalized onboarding, dedicated account management, and the ability to pay via invoice.",
            "type": "standard",
            "tax_category": "standard",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/Ws808ziTS76a6YbnMkiK_enterprise.png",
            "custom_data": {
              "features": {
                "aircraft_performance": true,
                "compliance_monitoring": true,
                "flight_log_management": true,
                "payment_by_invoice": true,
                "route_planning": true,
                "sso": true
              },
              "suggested_addons": [],
              "upgrade_description": "Ready to reach new heights? Upgrade to enterprise to unlock single sign-on, payment by invoice, and dedicated account management."
            },
            "status": "active",
            "created_at": "2023-02-23T12:44:34.923Z",
            "updated_at": "2024-04-05T15:58:28.309Z"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "50000",
            "tax": "4437",
            "discount": "0",
            "total": "54437"
          }
        },
        {
          "id": "txnitm_01j5dx3yqvsgxtvrj6f2zckeq1",
          "price_id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
          "quantity": 1,
          "totals": {
            "subtotal": "300000",
            "tax": "26625",
            "discount": "0",
            "total": "326625"
          },
          "product": {
            "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
            "name": "Reporting module",
            "description": "Get access to comprehensive reports and customizable analytics dashboards.",
            "type": "standard",
            "tax_category": "standard",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png",
            "custom_data": null,
            "status": "active",
            "created_at": "2023-02-23T13:58:17.615Z",
            "updated_at": "2024-04-05T15:44:02.893Z"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "300000",
            "tax": "26625",
            "discount": "0",
            "total": "326625"
          }
        },
        {
          "id": "txnitm_01j5dx3yqvsgxtvrj6fa55yjdt",
          "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "quantity": 1,
          "totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          },
          "product": {
            "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
            "name": "Custom domains",
            "description": "Make AeroEdit truly your own with custom domains. Custom domains reinforce your brand identity and make it easy for your team to access your account.",
            "type": "standard",
            "tax_category": "standard",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/XIG7UXoJQHmlIAiKcnkA_custom-domains.png",
            "custom_data": null,
            "status": "active",
            "created_at": "2023-02-23T14:01:02.441Z",
            "updated_at": "2024-04-05T15:43:28.971Z"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": null
    }
  },
  "meta": {
    "request_id": "5b956e6a-a1a4-4796-baf0-ba4cd13f38f6"
  }
}

Paddle automatically creates a subscription when you mark a manually-collected transaction as billed.

When you cancel an invoice, its related subscription isn't automatically canceled. The subscription keeps its current status. If it's active or past_due, a customer may still have access to your app, and Paddle sends a new invoice when the subscription renews.

Cancel using the Paddle dashboard or API

Use the Paddle dashboard or API to cancel the related subscription after you have canceled the transaction.

Build a workflow using webhooks

You can build a workflow to programmatically cancel subscriptions using webhooks:

  1. Subscribe to transaction canceled events
    Create or update a notification destination, then subscribe to transaction.canceled events.
  2. Check that the transaction is manually collected and for a subscription
    In the data payload for received events, check that collection_mode is manual and that subscription_id isn't null. This means the transaction is an issued invoice related to a subscription.
  3. Extract subscription ID, then cancel
    Extract subscription_id from the data payload, then use the cancel a subscription operation to cancel.

Cancel open invoices for a canceled subscription

When you cancel a manually-collected subscription, Paddle doesn't cancel its invoices. Invoices that are billed or past_due stay open and due. If a customer pays one of these invoices, Paddle doesn't reactivate the subscription.

To cancel open invoices after you cancel a subscription:

  • Invoices you created, where origin is api or web, can be canceled using the Paddle dashboard or API.
  • Invoices Paddle created for the subscription, like renewal invoices, can only be canceled using the Paddle dashboard.

Events

transaction.canceledOccurs when a transaction is canceled. Its status field changes to canceled.

Common errors

transaction_invalid_status_change
The status change you requested isn't valid from the transaction's current status.
transaction_cannot_be_modified_and_canceled
You're canceling a transaction while also sending other fields to update, which isn't allowed.
transaction_immutable_while_processing_payment
A payment attempt is in progress for this transaction, so it can't be updated right now.
forbidden
The authentication method you used doesn't have permission to perform that request.

Was this page helpful?