Version: 1.0
Last Updated: 2026-06-17
Base URL: https://cus-openapi.sifely.com
Audience: External developers integrating with Sifely Smart Lock API
Overview#
The Sifely API uses a subscription-based billing model with two metering dimensions: account devices (capacity) and API calls (usage). Every API client is bound 1:1 to a Sifely account. Devices paired in the Sifely App are automatically counted toward your plan quota — no manual enrollment required.
1. Plans & Pricing#
All prices in USD. Monthly billing only (no annual plans).| Plan | Monthly Fee | Device Limit | API Call Quota | Commercial Use | Webhook |
|---|
| Developer | $0 | 5 | 10,000 | ✗ Non-commercial only | ✓ |
| Starter | $9.90 | 50 | 500,000 | ✓ | ✓ |
| Pro | $17.90 | 100 | 1,000,000 | ✓ | ✓ |
| Custom | Contact Sales | > 100 | Custom | ✓ | ✓ |
⚠️ Pricing shown is subject to change. Final pricing is confirmed at the time of subscription.
1.1 Developer Plan Restrictions#
The Developer plan is intended for personal projects, integration testing, and non-commercial use. Commercial use — defined as any scenario where you charge customers/tenants, generate revenue, or manage paid-customer assets — requires a paid plan (Starter or above).1.2 Overage Pricing (Starter & Pro Only)#
When you exceed your plan's included quota, service continues uninterrupted. Overages are billed at the end of each billing cycle:| Dimension | Overage Rate | Billing Unit |
|---|
| Devices | $0.50 per device/month | Per device above limit |
| API Calls | $0.05 per 1,000 calls | Rounded up to nearest 1,000 |
Monthly Invoice = Base Plan Fee
+ max(0, Peak Devices − Device Limit) × $0.50
+ max(0, ceil((Total Calls − Call Quota) / 1,000)) × $0.05
| Scenario | Plan | Peak Devices | API Calls | Invoice |
|---|
| Within limits | Starter | 40 | 300,000 | $9.90 |
| Device overage | Starter | 60 | 300,000 | $14.90 |
| Call overage | Starter | 40 | 600,000 | $14.90 |
| Both overages | Pro | 110 | 1,200,000 | $33.90 |
1.3 Developer Plan — No Overage#
The Developer plan does not support overage. If either dimension exceeds the limit, all API calls return HTTP 429 until usage returns within limits. See Rate Limits & Quotas.
2. Usage Metering#
2.1 Account Devices#
| Aspect | Detail |
|---|
| What counts | All active devices on your bound Sifely account, regardless of whether they are accessed via API |
| Measurement | Daily snapshot at UTC 00:00 |
| Billing metric | Monthly peak — the highest daily snapshot within the billing cycle |
| Device removal | Removing a device from your Sifely account reduces the count in the next daily snapshot. The peak value already recorded for the current cycle is not adjusted |
Devices are managed in the Sifely App or Web Console (manager.sifely.com), not through the API.
2.2 API Calls#
| Aspect | Detail |
|---|
| What counts | Requests that enter the gateway and receive actual processing |
| Counted responses | 2xx (success) and 5xx (server error) |
| Not counted | 4xx (client error: 400, 401, 403, 404, etc.) — these are rejected before reaching business logic |
| Measurement | Real-time cumulative count within the billing cycle |
| Rounding | Overages are rounded up to the nearest 1,000 calls |
2.3 What Is NOT Counted#
Webhook deliveries — Server-initiated push events to your configured URL are not counted as API calls.
Developer Portal requests — Calls to /client/me, /subscription/me, /billing/*, and other portal management endpoints are internal and not metered.
3. Rate Limits & Quotas#
3.1 Monthly Quota Enforcement#
| Plan | Behavior When Quota Exceeded |
|---|
| Developer | Hard limit. Either dimension exceeding its cap triggers HTTP 429 on all API calls. Service auto-recovers when usage returns within limits (device count checked at next daily snapshot; call quota resets at cycle end). |
| Starter / Pro | Soft limit. Service continues. Overages are billed at end of cycle. |
3.2 Per-Second Rate Limits#
V1 does not enforce per-second rate limits (RPS). Monthly quotas provide natural throttling. Per-second burst protection may be introduced in a future version based on usage patterns.| State | API Behavior |
|---|
| Active subscription | Normal operation |
| Payment past due (D+0 to D+7) | Normal operation. Stripe retries payment automatically. You will receive email reminders to update your payment method. |
| Subscription canceled (after D+7 or manual cancel) | All API calls return HTTP 402 Payment Required. Account and data are preserved — resubscribe anytime to restore access. |
4. Billing Cycle#
4.1 Cycle Definition#
Starter / Pro: Follows your Stripe subscription cycle. The cycle starts on the day you subscribe (or upgrade) and renews monthly on that same day. Stripe handles month-end edge cases (e.g., subscribing on Jan 31 → next cycle Feb 28).
Developer: Internal cycle, rolling monthly from the date you selected the Developer plan. No invoices generated.
4.2 Invoice Timing#
| Event | When |
|---|
| Daily usage snapshot | UTC 00:00 |
| Invoice generation | End of billing cycle (automated by Stripe) |
| Payment collection | Immediately at invoice generation, from card on file |
| Invoice line items | (1) Base plan fee, (2) Device overage, (3) API call overage |
4.3 Estimated vs. Final Invoice#
The Developer Portal Billing page shows an estimated invoice based on accumulated usage (updated daily). This is a projection, not a commitment — the final invoice is calculated by Stripe at cycle end and may differ slightly.4.4 First Billing Day#
When you create a new subscription, the first device snapshot is taken at UTC 00:00 the following day. No snapshot runs on the subscription creation date itself.
5. Subscription Lifecycle#
| Aspect | Behavior |
|---|
| Effective | Immediately upon confirmation |
| Billing cycle | Resets. Old subscription ends; new cycle starts from upgrade date |
| Charges | Single invoice combining: (a) proration credit for unused time on old plan, (b) accumulated overages on old plan, (c) new plan fee. Net charge = (b) + (c) − (a) |
| Usage counters | Reset to zero for the new cycle |
Developer → Paid: No proration or overage settlement (Developer has no Stripe subscription). You are charged only the new plan's monthly fee.
5.2 Downgrade (Next Cycle)#
| Aspect | Behavior |
|---|
| Effective | At the end of the current billing cycle |
| Current cycle | Maintains original plan and quotas. No refund. |
| Usage check | None. You can downgrade regardless of current usage levels. |
| Downgrade to Developer | Requires acknowledgment of non-commercial use terms. If devices exceed 5, API service will pause until usage returns within limits. |
During the pending downgrade period, all plan changes (upgrade, further downgrade, cancellation) are frozen.
5.3 Cancellation#
| Aspect | Behavior |
|---|
| Applies to | Starter and Pro only (Developer has no subscription to cancel) |
| Effective | End of current billing cycle. No refund for the current period. |
| After cancellation | All API calls return HTTP 402. Account, data, and API key are preserved. |
| Resubscribe | Available anytime. Service restores immediately upon selecting a new plan. Your existing API key remains valid. |
During the pending cancellation period, all plan changes are frozen.
5.4 Payment Failure#
| Timeline | What Happens |
|---|
| D+0 → D+7 | Stripe retries payment automatically (Smart Retries). Email reminders sent. API service remains active. |
| D+7 | If still unpaid, subscription is automatically canceled. All API calls return HTTP 402. |
| After D+7 | Resubscribe at any time to restore service. Historical data is preserved. |
During payment past-due period (D+0 to D+7), all plan changes are frozen. You can only update your payment method.
6. Webhooks#
6.1 Configuration#
You can configure a single Webhook URL in the Developer Portal (Account & API Key page) to receive device event notifications. All plans, including Developer, support webhooks.| Setting | Detail |
|---|
| URL | Must be HTTPS. Validated on save (format check + HEAD probe). |
| Events | All device events (lock/unlock, status change, battery level, etc.) are forwarded — no event type filtering. |
| Billing impact | Webhook deliveries are not counted toward your API call quota. |
| Modification | Once saved, the URL is locked (read-only) in V1. Contact support to change it. |
⚠️ Webhook delivery is not yet active in V1. You will receive an email notification when delivery is enabled. Configuration can be completed now.
Detailed payload schema and delivery guarantees (retry policy, signature verification) will be documented when webhook delivery launches (see roadmap).
7. FAQ#
How are devices counted if I never call the API for some devices?#
All active devices on your Sifely account are counted, regardless of API usage. This is capacity-based billing — you pay for the devices available to your integration, not individual device API calls.What happens if I remove a device mid-month?#
The daily snapshot (UTC 00:00) will reflect the removal the next day. However, your monthly peak is already recorded — the highest device count seen during the cycle is used for billing. Removing devices does not retroactively reduce the peak.Do failed requests (4xx) count toward my quota?#
No. Only 2xx and 5xx responses are counted. Client errors (4xx) are not metered because they are rejected before reaching business logic.Can I exceed my Developer plan limits?#
No. Unlike paid plans, the Developer plan has a hard cap. Exceeding either the device limit (5) or call limit (10,000/month) triggers 429 responses on all requests until usage returns within limits.How do I check my current usage?#
1.
Developer Portal: The Usage page (/usage) shows real-time stats including total requests, device count, and daily API call charts.
2.
API Response Headers: Every API response includes X-RateLimit-Remaining and X-Device-Count headers.
3.
Billing Page: The estimated invoice on the Billing page (/billing) shows projected charges based on current usage.
What happens to my API key when I change plans?#
Your API key is preserved across all plan changes (upgrades, downgrades, cancellations, and resubscriptions). You only get a new key if you explicitly regenerate it.Can I switch from Developer to a paid plan at any time?#
Yes. Upgrading from Developer to Starter or Pro takes effect immediately. No proration or settlement is involved (Developer has no prior charges). You'll be charged the new plan's monthly fee upon confirmation.What if my payment fails on renewal?#
Stripe automatically retries for 7 days. During this period, your API access remains fully active. If payment still fails after 7 days, your subscription is canceled and all API calls return 402. You can resubscribe at any time to restore access — your data and API key are preserved.Is there a free trial for paid plans?#
No time-limited trial is offered. The Developer plan serves as a permanent free tier for testing and non-commercial use. For commercial evaluation, contact sales for a demo account.
| Resource | URL |
|---|
| Developer Portal | https://connect.sifely.com |
| Device Management | https://manager.sifely.com |
| Support | cs@sifely.com |
| Contact Sales | https://support.sifely.com/hc/en-us/requests/new |
Modified at 2026-06-17 12:43:13
