autumn

Fetch a single Autumn customer by id, optionally expanding related data (invoices, entities, subscriptions, balances). Autumn API: POST /v1/customers.get.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "Your unique identifier for the customer."
    },
    "expand": {
      "description": "Related data to expand, e.g. invoices, entities, subscriptions.plan, purchases.plan, balances.feature.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List/filter customers with cursor pagination. Autumn API: POST /v1/customers.list. Returns { list, next_cursor }.

{
  "type": "object",
  "properties": {
    "start_cursor": {
      "description": "Pagination cursor from a prior response's `next_cursor` (omit / empty for first page).",
      "type": "string"
    },
    "limit": {
      "description": "Page size, 1-5000. Default 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    },
    "plans": {
      "description": "Filter by plan: array of { id, versions? } objects.",
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "subscription_status": {
      "description": "Filter by status: \"active\" or \"scheduled\". Defaults to both.",
      "type": "string"
    },
    "search": {
      "description": "Search customers by id, name, or email.",
      "type": "string"
    },
    "processors": {
      "description": "Filter by processor type: stripe, revenuecat, vercel.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

READ-ONLY entitlement check: does a customer have access to (or enough balance of) a feature? Autumn API: POST /v1/balances.check. This tool never records usage — it does not expose send_event or lock.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "The ID of the customer."
    },
    "feature_id": {
      "type": "string",
      "description": "The ID of the feature to check."
    },
    "entity_id": {
      "description": "Entity id for entity-scoped balances (e.g. per-seat limits).",
      "type": "string"
    },
    "required_balance": {
      "description": "Minimum balance required for access. Returns allowed:false if below. Defaults to 1.",
      "type": "number"
    },
    "with_preview": {
      "description": "Include upgrade/upsell (paywall) info in the response when access is denied.",
      "type": "boolean"
    }
  },
  "required": [
    "customer_id",
    "feature_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List invoices with cursor pagination and optional filters. Autumn API: POST /v1/invoices.list. Returns { list, next_cursor }.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "description": "Filter to a single customer by id.",
      "type": "string"
    },
    "entity_id": {
      "description": "Filter to a single entity by id (must be paired with customer_id).",
      "type": "string"
    },
    "status": {
      "description": "Filter by invoice status: draft, open, paid, void, uncollectible.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "processor_types": {
      "description": "Filter by processor: stripe, revenuecat.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "start_cursor": {
      "description": "Pagination cursor from a prior response's `next_cursor` (omit / empty for first page).",
      "type": "string"
    },
    "limit": {
      "description": "Page size, 1-5000. Default 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch a single entity (e.g. a seat) belonging to a customer. Autumn API: POST /v1/entities.get.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "The ID of the customer that owns the entity."
    },
    "entity_id": {
      "type": "string",
      "description": "The ID of the entity."
    },
    "expand": {
      "description": "Related data to expand, e.g. invoices, entities, subscriptions.plan, purchases.plan, balances.feature.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "customer_id",
    "entity_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List a customer's entities with cursor pagination and optional filters. Autumn API: POST /v1/entities.list. Returns { list, next_cursor }.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "Restrict the response to entities owned by this customer id."
    },
    "start_cursor": {
      "description": "Pagination cursor from a prior response's `next_cursor` (omit / empty for first page).",
      "type": "string"
    },
    "limit": {
      "description": "Page size, 1-5000. Default 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    },
    "plans": {
      "description": "Filter by plan: array of { id, versions? } objects.",
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "subscription_status": {
      "description": "Filter by status: \"active\" or \"scheduled\". Defaults to both.",
      "type": "string"
    },
    "search": {
      "description": "Search entities by id or name.",
      "type": "string"
    },
    "processors": {
      "description": "Filter by parent customer processor: stripe, revenuecat, vercel.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List all features in the current environment. Autumn API: POST /v1/features.list. Returns { list }.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch a single feature by id. Autumn API: POST /v1/features.get.

{
  "type": "object",
  "properties": {
    "feature_id": {
      "type": "string",
      "description": "The ID of the feature."
    }
  },
  "required": [
    "feature_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List all plans (products) in the current environment. Autumn API: POST /v1/plans.list. Returns { list }.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "description": "Include eligibility info (trial availability, attach scenario) for this customer.",
      "type": "string"
    },
    "entity_id": {
      "description": "Entity id for entity-scoped plans.",
      "type": "string"
    },
    "include_archived": {
      "description": "If true, include archived plans.",
      "type": "boolean"
    },
    "all_versions": {
      "description": "If true, include all plan versions.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch a single plan by id (optionally a specific version). Autumn API: POST /v1/plans.get.

{
  "type": "object",
  "properties": {
    "plan_id": {
      "type": "string",
      "description": "The ID of the plan to retrieve."
    },
    "version": {
      "description": "The plan version to get. Defaults to the latest.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "plan_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Preview the cost/effect of attaching a plan to a customer WITHOUT charging or changing anything. Read-only. Autumn API: POST /v1/billing.preview_attach.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "The ID of the customer to attach the plan to."
    },
    "plan_id": {
      "type": "string",
      "description": "The ID of the plan."
    },
    "entity_id": {
      "description": "The ID of the entity to attach the plan to.",
      "type": "string"
    },
    "feature_quantities": {
      "description": "Prepaid feature quantities: array of { feature_id, quantity?, adjustable? }.",
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "version": {
      "description": "The version of the plan to attach.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "customize": {
      "description": "Optional plan overrides (price, items, licenses, free trial).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "customer_id",
    "plan_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Power-user escape hatch: POST to any Autumn read/preview endpoint not wrapped by a dedicated tool. READ-ONLY — the path is validated to only allow .get / .list / .check / .preview_* actions; write actions are rejected. Autumn API: POST {path}.

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Full API path, e.g. \"/v1/customers.get\". Only read/preview suffixes are allowed."
    },
    "body": {
      "description": "JSON body object to POST (the endpoint's params).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "path"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

MUTATES Autumn billing data — fetches a customer by id, creating them if they do not exist. Autumn API: POST /v1/customers.get_or_create.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Your unique identifier for the customer (null to create an anonymous customer)."
    },
    "name": {
      "description": "Customer's name.",
      "type": "string"
    },
    "email": {
      "description": "Customer's email address.",
      "type": "string"
    },
    "fingerprint": {
      "description": "Unique identifier to detect duplicate customers / prevent free-trial abuse.",
      "type": "string"
    },
    "metadata": {
      "description": "Arbitrary key/value metadata for the customer.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "stripe_id": {
      "description": "Existing Stripe customer id, if any.",
      "type": "string"
    },
    "create_in_stripe": {
      "description": "Whether to create the customer in Stripe.",
      "type": "boolean"
    },
    "currency": {
      "description": "Currency to bill this customer in (e.g. usd, eur).",
      "type": "string"
    },
    "expand": {
      "description": "Related data to expand, e.g. invoices, entities, subscriptions.plan, purchases.plan, balances.feature.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

MUTATES Autumn billing data — partially updates a customer. Only provided fields change. Autumn API: POST /v1/customers.update.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "ID of the customer to update."
    },
    "name": {
      "description": "Customer's name.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "email": {
      "description": "Customer's email address.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "fingerprint": {
      "description": "Duplicate-detection fingerprint.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "metadata": {
      "description": "Arbitrary key/value metadata for the customer.",
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "stripe_id": {
      "description": "Stripe customer id.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "currency": {
      "description": "Currency to bill this customer in (e.g. usd, eur).",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "new_customer_id": {
      "description": "New id for the customer.",
      "type": "string"
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

MUTATES Autumn billing data — records a usage event (deducts/credits a feature balance). Provide EITHER feature_id OR event_name. Autumn API: POST /v1/balances.track.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "The ID of the customer."
    },
    "feature_id": {
      "description": "The feature to track usage for. Provide this OR event_name.",
      "type": "string"
    },
    "event_name": {
      "description": "Event name to track usage for. Provide this OR feature_id.",
      "type": "string"
    },
    "value": {
      "description": "Amount of usage to record. Defaults to 1. Negative values credit the balance.",
      "type": "number"
    },
    "entity_id": {
      "description": "Entity id for entity-scoped balances.",
      "type": "string"
    },
    "properties": {
      "description": "Additional properties to attach to the usage event.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "timestamp": {
      "description": "Unix timestamp (ms) for the event. Defaults to now.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "idempotencyKey": {
      "description": "Optional key to dedupe retried events.",
      "type": "string"
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

MUTATES Autumn billing data — attaches (subscribes) a plan to a customer; may create an invoice / return a payment URL. Autumn API: POST /v1/billing.attach. Returns { customer_id, invoice, payment_url, required_action }.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "The ID of the customer to attach the plan to."
    },
    "plan_id": {
      "type": "string",
      "description": "The ID of the plan."
    },
    "entity_id": {
      "description": "The ID of the entity to attach the plan to.",
      "type": "string"
    },
    "feature_quantities": {
      "description": "Prepaid feature quantities: array of { feature_id, quantity?, adjustable? }.",
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "version": {
      "description": "The version of the plan to attach.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "success_url": {
      "description": "URL to redirect to after a successful checkout.",
      "type": "string"
    },
    "redirect_mode": {
      "description": "Checkout redirect mode: always, if_required, or never.",
      "type": "string"
    },
    "invoice_mode": {
      "description": "Invoice-mode configuration object (send an invoice instead of auto-charging).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "checkout_session_params": {
      "description": "Extra Stripe checkout session params (can carry metadata).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "customize": {
      "description": "Optional plan overrides (price, items, licenses, free trial).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "customer_id",
    "plan_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

MUTATES Autumn billing data — creates an entity (e.g. a seat) under a customer, tied to a feature. Autumn API: POST /v1/entities.create.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "The ID of the customer to create the entity for."
    },
    "entity_id": {
      "type": "string",
      "description": "The ID of the entity."
    },
    "feature_id": {
      "type": "string",
      "description": "The ID of the feature this entity is associated with."
    },
    "name": {
      "description": "The name of the entity.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "billing_controls": {
      "description": "Optional billing controls for the entity (spend/usage limits).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "customer_id",
    "entity_id",
    "feature_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

MUTATES Autumn billing data — creates a Stripe billing-portal session for a customer to manage their subscription. Autumn API: POST /v1/billing.open_customer_portal. Returns { customer_id, url }.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "The ID of the customer to open the billing portal for."
    },
    "return_url": {
      "description": "URL to redirect to when the back button is clicked in the portal.",
      "type": "string"
    },
    "configuration_id": {
      "description": "Stripe billing-portal configuration id.",
      "type": "string"
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}