Skip to main content
POST
/
v1
/
billing.import
Typescript (SDK)
import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.billing.import({
  customerId: "cus_123",
  processors: [
    {
      type: "stripe",
      id: "cus_stripe_123",
    },
  ],
  billables: [
    {
      processor: "stripe",
      link: {
        subscriptionId: "sub_123",
      },
      plan: {
        planId: "pro",
        status: "active",
        balances: [
          {
            featureId: "messages",
            usage: 10,
          },
        ],
      },
    },
  ],
});
{
  "customer_id": "cus_123",
  "flashed": [
    {
      "plan_id": "pro",
      "processor": "stripe",
      "customer_product_id": "cus_prod_123",
      "status": "active",
      "skipped": false
    }
  ],
  "customer": {
    "id": "cus_123",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "createdAt": 1771409161016,
    "fingerprint": null,
    "stripeId": "cus_stripe_123",
    "processors": {
      "stripe": {
        "id": "cus_stripe_123"
      }
    },
    "env": "sandbox",
    "metadata": {},
    "sendEmailReceipts": false,
    "billingControls": {
      "autoTopups": []
    },
    "subscriptions": [
      {
        "planId": "pro",
        "autoEnable": false,
        "addOn": false,
        "status": "active",
        "pastDue": false,
        "canceledAt": null,
        "expiresAt": null,
        "trialEndsAt": null,
        "startedAt": 1771431921437,
        "currentPeriodStart": 1771431921437,
        "currentPeriodEnd": 1771999921437,
        "quantity": 1
      }
    ],
    "purchases": [],
    "balances": {
      "messages": {
        "featureId": "messages",
        "granted": 100,
        "remaining": 90,
        "usage": 10,
        "unlimited": false,
        "overageAllowed": false,
        "maxPurchase": null,
        "nextResetAt": 1773851121437,
        "breakdown": [
          {
            "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
            "planId": "pro",
            "includedGrant": 100,
            "prepaidGrant": 0,
            "remaining": 90,
            "usage": 10,
            "unlimited": false,
            "reset": {
              "interval": "month",
              "resetsAt": 1773851121437
            },
            "price": null,
            "expiresAt": null
          }
        ]
      }
    },
    "flags": {},
    "config": {
      "disable_pooled_balance": false,
      "disable_overage_billing": false
    }
  }
}

​
Body Parameters

​
Response

{
  "customer_id": "cus_123",
  "flashed": [
    {
      "plan_id": "pro",
      "processor": "stripe",
      "customer_product_id": "cus_prod_123",
      "status": "active",
      "skipped": false
    }
  ],
  "customer": {
    "id": "cus_123",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "createdAt": 1771409161016,
    "fingerprint": null,
    "stripeId": "cus_stripe_123",
    "processors": {
      "stripe": {
        "id": "cus_stripe_123"
      }
    },
    "env": "sandbox",
    "metadata": {},
    "sendEmailReceipts": false,
    "billingControls": {
      "autoTopups": []
    },
    "subscriptions": [
      {
        "planId": "pro",
        "autoEnable": false,
        "addOn": false,
        "status": "active",
        "pastDue": false,
        "canceledAt": null,
        "expiresAt": null,
        "trialEndsAt": null,
        "startedAt": 1771431921437,
        "currentPeriodStart": 1771431921437,
        "currentPeriodEnd": 1771999921437,
        "quantity": 1
      }
    ],
    "purchases": [],
    "balances": {
      "messages": {
        "featureId": "messages",
        "granted": 100,
        "remaining": 90,
        "usage": 10,
        "unlimited": false,
        "overageAllowed": false,
        "maxPurchase": null,
        "nextResetAt": 1773851121437,
        "breakdown": [
          {
            "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
            "planId": "pro",
            "includedGrant": 100,
            "prepaidGrant": 0,
            "remaining": 90,
            "usage": 10,
            "unlimited": false,
            "reset": {
              "interval": "month",
              "resetsAt": 1773851121437
            },
            "price": null,
            "expiresAt": null
          }
        ]
      }
    },
    "flags": {},
    "config": {
      "disable_pooled_balance": false,
      "disable_overage_billing": false
    }
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-api-version
string
default:2.3.0
required

Body

application/json
​
customer_id
string
required

Autumn customer to image into.

​
billables
object[]
required

The billing objects (subscriptions, one-offs) to image, each carrying its plan.

​
customer_data
object

Optional identity fields to upsert if the customer is new.

​
processors
object[]

The customer's processor identities (e.g. Stripe customer id, RevenueCat app_user_id). Omit for customers with no processor, e.g. those only ever on a free plan.

​
dry_run
boolean

If true, validate and compute without persisting; returns what would be flashed.

Response

200 - application/json

OK

​
customer_id
string
required

The imaged customer's id.

​
flashed
object[]
required

Per-plan outcome of the flash.

​
customer
object | null
required

The freshly-read imaged customer; null for dry_run.

Example:
{
  "id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
  "name": "Patrick",
  "email": "patrick@useautumn.com",
  "fingerprint": null,
  "processors": { "stripe": { "id": "cus_U0BKxpq1mFhuJO" } },
  "env": "sandbox",
  "metadata": {},
  "subscriptions": [
    {
      "planId": "pro_plan",
      "autoEnable": true,
      "addOn": false,
      "status": "active",
      "pastDue": false,
      "canceledAt": null,
      "expiresAt": null,
      "trialEndsAt": null,
      "startedAt": 1771431921437,
      "currentPeriodStart": 1771431921437,
      "currentPeriodEnd": 1771999921437,
      "quantity": 1
    }
  ],
  "purchases": [],
  "balances": {
    "messages": {
      "featureId": "messages",
      "granted": 100,
      "remaining": 0,
      "usage": 100,
      "unlimited": false,
      "overageAllowed": false,
      "maxPurchase": null,
      "nextResetAt": 1773851121437,
      "breakdown": [
        {
          "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
          "planId": "pro_plan",
          "includedGrant": 100,
          "prepaidGrant": 0,
          "remaining": 0,
          "usage": 100,
          "unlimited": false,
          "reset": {
            "interval": "month",
            "resetsAt": 1773851121437
          },
          "price": null,
          "expiresAt": null
        }
      ]
    }
  },
  "flags": {
    "advanced_workflows": {
      "id": "cus_ent_abc123",
      "plan_id": "pro_plan",
      "expires_at": null,
      "feature_id": "advanced_workflows"
    }
  },
  "config": {
    "disable_pooled_balance": false,
    "disable_overage_billing": false
  }
}