Update Customer

Updates an existing customer’s information by ID.

This endpoint can also be called using PATCH /v1/customers/{customer_id} for REST-style updates.

Request Body

customer_id · string · required

ID of the customer to update.

name · string

Customer’s name. Pass null to clear the value.

email · string

Customer’s email address. Must be a valid email format. Pass null to clear the value.

fingerprint · string

Unique identifier (eg. serial number, device ID) to detect duplicate customers. Pass null to clear the value.

metadata · object

Additional metadata for the customer. Pass null to clear all metadata, or provide an object to merge with existing metadata.

stripe_id · string

Stripe customer ID. Use this to link the customer to an existing Stripe customer. Pass null to clear the value.

send_email_receipts · boolean

Whether to send email receipts to this customer.

new_customer_id · string

New ID for the customer if you want to change their identifier. The new ID must follow the same validation rules as the original ID (no @, spaces, or periods).

Response

Returns the updated Customer object with the following fields:

id · string

Your unique identifier for the customer (or the new ID if new_customer_id was provided).

name · string

The updated name of the customer.

email · string

The updated email address of the customer.

created_at · number

Timestamp of customer creation in milliseconds since epoch (unchanged).

fingerprint · string

The updated fingerprint identifier for the customer.

stripe_id · string

Updated Stripe customer ID.

env · string

The environment this customer was created in (sandbox or live).

metadata · object

The updated metadata for the customer.

send_email_receipts · boolean

Whether email receipts are enabled for this customer.

subscriptions · array

Active and scheduled recurring plans (unchanged by this operation).

purchases · array

One-time purchases (unchanged by this operation).

balances · object

Feature balances (unchanged by this operation).

Example Requests

Update Basic Info

const customer = await autumn.customers.update({
  customer_id: "cus_123",
  name: "Jane Doe",
  email: "[e-mail]"
});

const customer = await autumn.customers.update({
  customer_id: "cus_123",
  metadata: {
    company: "New Company Inc",
    department: "Engineering",
    custom_field: "value"
  }
});

const customer = await autumn.customers.update({
  customer_id: "cus_123",
  new_customer_id: "cus_new_id_456"
});

const customer = await autumn.customers.update({
  customer_id: "cus_123",
  send_email_receipts: true
});

customer = autumn.customers.update(
    customer_id="cus_123",
    name="Jane Doe",
    email="[e-mail]",
    metadata={
        "company": "New Company Inc"
    }
)

curl -X POST https://api.useautumn.com/v1/customers.update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: 2.1" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_123",
    "name": "Jane Doe",
    "email": "[e-mail]",
    "metadata": {
      "company": "New Company Inc"
    }
  }'

curl -X PATCH https://api.useautumn.com/v1/customers/cus_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: 2.1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "[e-mail]"
  }'

Example Response

{
  "id": "cus_123",
  "name": "Jane Doe",
  "email": "[e-mail]",
  "created_at": 1771409161016,
  "fingerprint": null,
  "stripe_id": "cus_U0BKxpq1mFhuJO",
  "env": "sandbox",
  "metadata": {
    "company": "New Company Inc",
    "department": "Engineering"
  },
  "send_email_receipts": false,
  "subscriptions": [
    {
      "plan_id": "pro_plan",
      "auto_enable": true,
      "add_on": false,
      "status": "active",
      "past_due": false,
      "canceled_at": null,
      "expires_at": null,
      "trial_ends_at": null,
      "started_at": 1771431921437,
      "current_period_start": 1771431921437,
      "current_period_end": 1771999921437,
      "quantity": 1
    }
  ],
  "purchases": [],
  "balances": {
    "messages": {
      "feature_id": "messages",
      "granted": 100,
      "remaining": 50,
      "usage": 50,
      "unlimited": false,
      "overage_allowed": false,
      "max_purchase": null,
      "next_reset_at": 1773851121437,
      "breakdown": [
        {
          "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
          "plan_id": "pro_plan",
          "included_grant": 100,
          "prepaid_grant": 0,
          "remaining": 50,
          "usage": 50,
          "unlimited": false,
          "reset": {
            "interval": "month",
            "resets_at": 1773851121437
          },
          "price": null,
          "expires_at": null
        }
      ]
    }
  }
}

Notes

• Only the fields you provide in the request will be updated. Other fields remain unchanged.
• To clear a nullable field, explicitly pass null as the value.
• When updating metadata, the provided object is merged with existing metadata. To completely replace metadata, pass the complete new object.
• Changing the customer ID with new_customer_id will update the ID across all related records (subscriptions, balances, etc.).