Customer Timezones

Bill customers in their local timezone. Set a timezone on a customer and Flexprice automatically aligns billing periods, usage windows, entitlement resets, and credit expirations to their local calendar.

When you serve customers across geographies, billing in UTC creates a visible problem: a customer in Bangalore on a monthly plan ends their billing period at 5:30 AM local time, not midnight. Their invoice covers dates that do not match their calendar, and usage that feels like “this month” to them lands on “next month’s” invoice. Customer timezones fix this by aligning every billing boundary to the customer’s local time.

---

How It Works

Set a timezone on the customer record. Flexprice then aligns the following to the customer’s local calendar:

• Billing period start and end: each period (daily, weekly, monthly, quarterly, half-yearly, annual) begins and ends at local midnight.
• Usage windows: usage is aggregated per local day or month, not UTC.
• Entitlement resets: daily and monthly usage limits reset at local midnight.
• Credit grants: prepaid credits expiring at period-end use the customer’s local boundary.
• Coupon end dates: coupons tied to billing periods expire at the local period boundary.

Customers without a timezone set default to UTC.

---

Setting Up

Via the API

Set the timezone field when creating a customer, or update it at any time:

# Create a customer with a timezone
curl -X POST https://us.api.flexprice.io/v1/customers \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "cust_001",
    "name": "Acme India",
    "email": "[e-mail]",
    "timezone": "Asia/Kolkata"
  }'

# Update an existing customer's timezone
curl -X PATCH https://us.api.flexprice.io/v1/customers/{id} \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/Los_Angeles"
  }'

Updating a customer’s timezone does not affect active subscriptions. Only new subscriptions created after the update will use the new timezone.

Use standard IANA timezone names. Common examples:

Region	IANA Name
India (IST)	Asia/Kolkata
US Eastern	America/New_York
US Pacific	America/Los_Angeles
Germany	Europe/Berlin
UK	Europe/London
Singapore	Asia/Singapore
Australia Eastern	Australia/Sydney
Nepal	Asia/Kathmandu

Invalid timezone names are rejected with HTTP 400.

Via the Dashboard

When creating or editing a customer, select the timezone from the Timezone dropdown. It applies to all future subscriptions for that customer.

If no timezone is selected, the customer defaults to UTC.

---

What Stays the Same

Changing a customer’s timezone does not affect how you send events or how historical data is stored. Your event pipeline requires no changes.

Existing customers without a timezone and their historical subscriptions are unaffected.

---

Example

A customer in India (IST, UTC+5:30) on a monthly calendar plan:

	Without timezone	With timezone (IST)
Daily usage resets at	5:30 AM IST	12:00 AM IST ✓
Entitlement resets at	5:30 AM IST	12:00 AM IST ✓
Invoice period	March 15 – April 1 (UTC dates)	March 15 – April 1 (IST dates) ✓

---

Limitations

Changing timezone on an active subscription

Updating a customer’s timezone only applies to new subscriptions. To rebill an existing subscription under a new timezone, cancel it and create a new one.

Non-standard offsets

Half-hour and 45-minute offsets such as India (UTC+5:30), Nepal (UTC+5:45), and Newfoundland (UTC-3:30) are fully supported.

---

Related Articles

Creating a Customer

Create customers via the dashboard or API.

Creating a Subscription

Create a subscription and set the start date for a customer.

Wallet & Credit Grants

Credit grants that expire at billing period boundaries respect the customer’s timezone.

Coupons

Coupons tied to billing periods use the customer’s local timezone for expiry.

---

API References

• Create a Customer
• Update a Customer
• Create a Subscription