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.

Skip to content
Docs

Cancel an invoice

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

AI summary

Cancel a billed or ready manually-collected transaction to mark an invoice as no longer due, which also invalidates its payment links and excludes it from revenue reports.

  • • PATCH with status: 'canceled' — only manual transactions in billed or ready status can be canceled; completed ones need adjustments instead.
  • • Canceling an invoice does not cancel the related subscription — handle that separately via the dashboard, API, or a transaction.canceled webhook.
  • • A credit adjustment can correct some invoice errors without canceling — for example, crediting the value of a line item reduces the amount owed rather than voiding the entire invoice.

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 billed (issued invoices) or ready. 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.

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. You don't need to include anything else.

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. This means the subscription remains active, so a customer may still have access to your app. Paddle reinvoices for the subscription on renewal.

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.

Events

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

Common errors

transaction_invalid_status_change
Invalid status change attempted
transaction_immutable
You are trying to update a transaction which is not in the draft or ready state.

Was this page helpful?