Skip to main content

Troubleshooting Billing and Plans

Use this guide when Imgwire reports a billing or plan error, usage looks unexpected, a custom domain is blocked by plan access, or uploads are stopped by storage or upload capacity.

Billing state can block operations​

Some Resource API operations require an organization with an active billing state. If your organization is inactive or canceled, operations that require an active organization can fail with PaymentRequiredError.

The API returns Imgwire domain errors in this shape:

{
  "detail": "Organization must have an active subscription to perform this operation.",
  "error_type": "PaymentRequiredError"
}

Open the dashboard Billing page and confirm the organization has an active plan, valid payment method, and no blocking billing issue.

Usage limits that affect integrations​

Billing plans include limits and capabilities such as:

  • Storage bytes.
  • Transfer bytes.
  • Uploads.
  • Transformations.
  • Maximum pending uploads.
  • Custom domain access.
  • Team member limits.
  • Enhanced analytics and support features, depending on plan.

If a plan or quota limit blocks an operation, the API can return PaymentRequiredError. Upload creation can also be blocked when the organization has used its upload capacity for the quota period or when current stored original image bytes exceed the plan's storage limit.

Storage is a current-capacity limit, not a monthly counter. Deleting images you no longer need can reduce storage usage. Uploads, transformations, and transfer are tracked through usage periods for reporting and quota enforcement.

Usage metrics look wrong​

Use the dashboard Metrics page or the Metrics Resource API to inspect usage by Environment.

Important details:

  • uploads count when image records are created, uploaded, and moved to READY.
  • storage_bytes tracks original uploaded image bytes for storage capacity.
  • Transformed variants are tracked through transformation usage, not as user-visible original-image storage.
  • transformations count when Imgwire computes a new transformed variant; serving an already cached variant does not create a new transformation event.
  • transfer_bytes is the CDN bandwidth used for served images and variants.
  • Metrics are rolled up asynchronously, so recent activity may not appear immediately.

When comparing usage, check the date range, interval, and time zone in the metrics view.

Custom domain not available​

Custom domains are plan-gated. If creating a custom domain returns a billing or plan error, confirm that the current organization plan includes custom domains.

Also confirm you are configuring the custom domain in the correct Environment. Each Environment can have only one custom domain.

Team or organization access is blocked​

Plan limits can affect team-member management. If inviting or adding a member fails, confirm the current plan's team member limit and current member count.

Organization roles also matter. If you can view billing but cannot make a change, ask an organization owner or admin to check your role.

Payment and invoice questions​

The dashboard Billing page is the right place to review the current plan, payment method, invoices, subscription state, and cancellation state.

If a payment, invoice, or subscription state does not look right, include these details when you contact support:

  • Organization name.
  • Billing email, if different from your login email.
  • Invoice number or billing period.
  • Last four digits and card brand shown in the dashboard, if relevant.
  • What action you were attempting, such as changing plan or updating payment method.

Do not send full payment card numbers or sensitive payment credentials to support.

Last updated at: May 8, 2026