orb-billing 3.2.0 → 4.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +21 -0
- package/package.json +2 -2
- package/resources/alerts.d.ts +9 -9
- package/resources/alerts.d.ts.map +1 -1
- package/resources/alerts.js.map +1 -1
- package/resources/alerts.mjs.map +1 -1
- package/resources/customers/customers.d.ts +0 -7
- package/resources/customers/customers.d.ts.map +1 -1
- package/resources/customers/customers.js +0 -3
- package/resources/customers/customers.js.map +1 -1
- package/resources/customers/customers.mjs +0 -3
- package/resources/customers/customers.mjs.map +1 -1
- package/resources/customers/index.d.ts +0 -1
- package/resources/customers/index.d.ts.map +1 -1
- package/resources/customers/index.js +1 -3
- package/resources/customers/index.js.map +1 -1
- package/resources/customers/index.mjs +0 -1
- package/resources/customers/index.mjs.map +1 -1
- package/resources/events/backfills.d.ts +42 -0
- package/resources/events/backfills.d.ts.map +1 -1
- package/resources/events/backfills.js +6 -0
- package/resources/events/backfills.js.map +1 -1
- package/resources/events/backfills.mjs +6 -0
- package/resources/events/backfills.mjs.map +1 -1
- package/resources/events/events.d.ts +11 -2
- package/resources/events/events.d.ts.map +1 -1
- package/resources/events/events.js +11 -2
- package/resources/events/events.js.map +1 -1
- package/resources/events/events.mjs +11 -2
- package/resources/events/events.mjs.map +1 -1
- package/resources/plans/plans.d.ts +15 -15
- package/resources/plans/plans.d.ts.map +1 -1
- package/resources/prices/prices.d.ts +108 -18
- package/resources/prices/prices.d.ts.map +1 -1
- package/resources/prices/prices.js.map +1 -1
- package/resources/prices/prices.mjs.map +1 -1
- package/resources/subscriptions.d.ts +20 -30
- package/resources/subscriptions.d.ts.map +1 -1
- package/resources/subscriptions.js.map +1 -1
- package/resources/subscriptions.mjs.map +1 -1
- package/src/resources/alerts.ts +24 -9
- package/src/resources/customers/customers.ts +0 -7
- package/src/resources/customers/index.ts +0 -7
- package/src/resources/events/backfills.ts +48 -0
- package/src/resources/events/events.ts +11 -2
- package/src/resources/plans/plans.ts +15 -15
- package/src/resources/prices/prices.ts +162 -18
- package/src/resources/subscriptions.ts +20 -32
- package/src/version.ts +1 -1
- package/version.d.ts +1 -1
- package/version.js +1 -1
- package/version.mjs +1 -1
- package/resources/customers/usage.d.ts +0 -326
- package/resources/customers/usage.d.ts.map +0 -1
- package/resources/customers/usage.js +0 -227
- package/resources/customers/usage.js.map +0 -1
- package/resources/customers/usage.mjs +0 -223
- package/resources/customers/usage.mjs.map +0 -1
- package/src/resources/customers/usage.ts +0 -372
|
@@ -3535,12 +3535,6 @@ export interface SubscriptionFetchUsageParams {
|
|
|
3535
3535
|
*/
|
|
3536
3536
|
billable_metric_id?: string | null;
|
|
3537
3537
|
|
|
3538
|
-
/**
|
|
3539
|
-
* Cursor for pagination. This can be populated by the `next_cursor` value returned
|
|
3540
|
-
* from the initial request.
|
|
3541
|
-
*/
|
|
3542
|
-
cursor?: string | null;
|
|
3543
|
-
|
|
3544
3538
|
first_dimension_key?: string | null;
|
|
3545
3539
|
|
|
3546
3540
|
first_dimension_value?: string | null;
|
|
@@ -3555,12 +3549,6 @@ export interface SubscriptionFetchUsageParams {
|
|
|
3555
3549
|
*/
|
|
3556
3550
|
group_by?: string | null;
|
|
3557
3551
|
|
|
3558
|
-
/**
|
|
3559
|
-
* If including a `group_by`, the number of groups to fetch data for. Defaults
|
|
3560
|
-
* to 1000.
|
|
3561
|
-
*/
|
|
3562
|
-
limit?: number | null;
|
|
3563
|
-
|
|
3564
3552
|
second_dimension_key?: string | null;
|
|
3565
3553
|
|
|
3566
3554
|
second_dimension_value?: string | null;
|
|
@@ -3759,7 +3747,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
3759
3747
|
/**
|
|
3760
3748
|
* The cadence to bill for this price on.
|
|
3761
3749
|
*/
|
|
3762
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
3750
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
3763
3751
|
|
|
3764
3752
|
/**
|
|
3765
3753
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -3834,7 +3822,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
3834
3822
|
/**
|
|
3835
3823
|
* The cadence to bill for this price on.
|
|
3836
3824
|
*/
|
|
3837
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
3825
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
3838
3826
|
|
|
3839
3827
|
/**
|
|
3840
3828
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -3915,7 +3903,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
3915
3903
|
/**
|
|
3916
3904
|
* The cadence to bill for this price on.
|
|
3917
3905
|
*/
|
|
3918
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
3906
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
3919
3907
|
|
|
3920
3908
|
/**
|
|
3921
3909
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4016,7 +4004,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4016
4004
|
/**
|
|
4017
4005
|
* The cadence to bill for this price on.
|
|
4018
4006
|
*/
|
|
4019
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4007
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4020
4008
|
|
|
4021
4009
|
/**
|
|
4022
4010
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4122,7 +4110,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4122
4110
|
/**
|
|
4123
4111
|
* The cadence to bill for this price on.
|
|
4124
4112
|
*/
|
|
4125
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4113
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4126
4114
|
|
|
4127
4115
|
/**
|
|
4128
4116
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4216,7 +4204,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4216
4204
|
/**
|
|
4217
4205
|
* The cadence to bill for this price on.
|
|
4218
4206
|
*/
|
|
4219
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4207
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4220
4208
|
|
|
4221
4209
|
/**
|
|
4222
4210
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4318,7 +4306,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4318
4306
|
/**
|
|
4319
4307
|
* The cadence to bill for this price on.
|
|
4320
4308
|
*/
|
|
4321
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4309
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4322
4310
|
|
|
4323
4311
|
/**
|
|
4324
4312
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4398,7 +4386,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4398
4386
|
/**
|
|
4399
4387
|
* The cadence to bill for this price on.
|
|
4400
4388
|
*/
|
|
4401
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4389
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4402
4390
|
|
|
4403
4391
|
/**
|
|
4404
4392
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4493,7 +4481,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4493
4481
|
/**
|
|
4494
4482
|
* The cadence to bill for this price on.
|
|
4495
4483
|
*/
|
|
4496
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4484
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4497
4485
|
|
|
4498
4486
|
/**
|
|
4499
4487
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4580,7 +4568,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4580
4568
|
/**
|
|
4581
4569
|
* The cadence to bill for this price on.
|
|
4582
4570
|
*/
|
|
4583
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4571
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4584
4572
|
|
|
4585
4573
|
/**
|
|
4586
4574
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4646,7 +4634,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4646
4634
|
/**
|
|
4647
4635
|
* The cadence to bill for this price on.
|
|
4648
4636
|
*/
|
|
4649
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4637
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4650
4638
|
|
|
4651
4639
|
/**
|
|
4652
4640
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4712,7 +4700,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4712
4700
|
/**
|
|
4713
4701
|
* The cadence to bill for this price on.
|
|
4714
4702
|
*/
|
|
4715
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4703
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4716
4704
|
|
|
4717
4705
|
/**
|
|
4718
4706
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4778,7 +4766,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4778
4766
|
/**
|
|
4779
4767
|
* The cadence to bill for this price on.
|
|
4780
4768
|
*/
|
|
4781
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4769
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4782
4770
|
|
|
4783
4771
|
/**
|
|
4784
4772
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4844,7 +4832,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4844
4832
|
/**
|
|
4845
4833
|
* The cadence to bill for this price on.
|
|
4846
4834
|
*/
|
|
4847
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4835
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4848
4836
|
|
|
4849
4837
|
/**
|
|
4850
4838
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4910,7 +4898,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4910
4898
|
/**
|
|
4911
4899
|
* The cadence to bill for this price on.
|
|
4912
4900
|
*/
|
|
4913
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4901
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4914
4902
|
|
|
4915
4903
|
/**
|
|
4916
4904
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -4976,7 +4964,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
4976
4964
|
/**
|
|
4977
4965
|
* The cadence to bill for this price on.
|
|
4978
4966
|
*/
|
|
4979
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
4967
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
4980
4968
|
|
|
4981
4969
|
/**
|
|
4982
4970
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -5042,7 +5030,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
5042
5030
|
/**
|
|
5043
5031
|
* The cadence to bill for this price on.
|
|
5044
5032
|
*/
|
|
5045
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
5033
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
5046
5034
|
|
|
5047
5035
|
/**
|
|
5048
5036
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -5108,7 +5096,7 @@ export namespace SubscriptionPriceIntervalsParams {
|
|
|
5108
5096
|
/**
|
|
5109
5097
|
* The cadence to bill for this price on.
|
|
5110
5098
|
*/
|
|
5111
|
-
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
|
|
5099
|
+
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
|
|
5112
5100
|
|
|
5113
5101
|
/**
|
|
5114
5102
|
* An ISO 4217 currency string for which this price is billed in.
|
|
@@ -5317,12 +5305,12 @@ export interface SubscriptionSchedulePlanChangeParams {
|
|
|
5317
5305
|
|
|
5318
5306
|
/**
|
|
5319
5307
|
* [DEPRECATED] Use billing_cycle_alignment instead. Reset billing periods to be
|
|
5320
|
-
* aligned with the plan change
|
|
5308
|
+
* aligned with the plan change's effective date.
|
|
5321
5309
|
*/
|
|
5322
5310
|
align_billing_with_plan_change_date?: boolean | null;
|
|
5323
5311
|
|
|
5324
5312
|
/**
|
|
5325
|
-
* Reset billing periods to be aligned with the plan change
|
|
5313
|
+
* Reset billing periods to be aligned with the plan change's effective date or
|
|
5326
5314
|
* start of the month. Defaults to `unchanged` which keeps subscription's existing
|
|
5327
5315
|
* billing cycle alignment.
|
|
5328
5316
|
*/
|
package/src/version.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export const VERSION = '
|
|
1
|
+
export const VERSION = '4.1.0'; // x-release-please-version
|
package/version.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export declare const VERSION = "
|
|
1
|
+
export declare const VERSION = "4.1.0";
|
|
2
2
|
//# sourceMappingURL=version.d.ts.map
|
package/version.js
CHANGED
package/version.mjs
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export const VERSION = '
|
|
1
|
+
export const VERSION = '4.1.0'; // x-release-please-version
|
|
2
2
|
//# sourceMappingURL=version.mjs.map
|
|
@@ -1,326 +0,0 @@
|
|
|
1
|
-
import { APIResource } from "../../resource.js";
|
|
2
|
-
import * as Core from "../../core.js";
|
|
3
|
-
import * as UsageAPI from "./usage.js";
|
|
4
|
-
export declare class Usage extends APIResource {
|
|
5
|
-
/**
|
|
6
|
-
* This endpoint is used to amend usage within a timeframe for a customer that has
|
|
7
|
-
* an active subscription.
|
|
8
|
-
*
|
|
9
|
-
* This endpoint will mark _all_ existing events within
|
|
10
|
-
* `[timeframe_start, timeframe_end)` as _ignored_ for billing purposes, and Orb
|
|
11
|
-
* will only use the _new_ events passed in the body of this request as the source
|
|
12
|
-
* of truth for that timeframe moving forwards. Note that a given time period can
|
|
13
|
-
* be amended any number of times, so events can be overwritten in subsequent calls
|
|
14
|
-
* to th is endpoint.
|
|
15
|
-
*
|
|
16
|
-
* This is a powerful and audit-safe mechanism to retroactively change usage data
|
|
17
|
-
* in cases where you need to:
|
|
18
|
-
*
|
|
19
|
-
* - decrease historical usage consumption because of degraded service availability
|
|
20
|
-
* in your systems
|
|
21
|
-
* - account for gaps from your usage reporting mechanism
|
|
22
|
-
* - make point-in-time fixes for specific event records, while retaining the
|
|
23
|
-
* original time of usage and associated metadata. This amendment API is designed
|
|
24
|
-
* with two explicit goals:
|
|
25
|
-
*
|
|
26
|
-
* 1. Amendments are **always audit-safe**. The amendment process will still retain
|
|
27
|
-
* original events in the timeframe, though they will be ignored for billing
|
|
28
|
-
* calculations. For auditing a nd data fidelity purposes, Orb never overwrites
|
|
29
|
-
* or permanently deletes ingested usage data.
|
|
30
|
-
* 2. Amendments always preserve data **consistency**. In other words, either an
|
|
31
|
-
* amendment is fully processed by the system (and the new events for the
|
|
32
|
-
* timeframe are honored rather than the existing ones) or the amendment request
|
|
33
|
-
* fails. To maintain this important property, Orb prevents _partial event
|
|
34
|
-
* ingestion_ on this endpoint.
|
|
35
|
-
*
|
|
36
|
-
* ## Response semantics
|
|
37
|
-
*
|
|
38
|
-
* - Either all events are ingested successfully, or all fail to ingest (returning
|
|
39
|
-
* a `4xx` or `5xx` response code).
|
|
40
|
-
* - Any event that fails schema validation will lead to a `4xx` response. In this
|
|
41
|
-
* case, to maintain data consistency, Orb will not ingest any events and will
|
|
42
|
-
* also not deprecate existing events in the time period.
|
|
43
|
-
* - You can assume that the amendment is successful on receipt of a `2xx`
|
|
44
|
-
* response.While a successful response from this endpoint indicates that the new
|
|
45
|
-
* events have been ingested, updating usage totals happens asynchronously and
|
|
46
|
-
* may be delayed by a few minutes.
|
|
47
|
-
*
|
|
48
|
-
* As emphasized above, Orb will never show an inconsistent state (e.g. in invoice
|
|
49
|
-
* previews or dashboards); either it will show the existing state (before the
|
|
50
|
-
* amendment) or the new state (with new events in the requested timeframe).
|
|
51
|
-
*
|
|
52
|
-
* ## Sample request body
|
|
53
|
-
*
|
|
54
|
-
* ```json
|
|
55
|
-
* {
|
|
56
|
-
* "events": [
|
|
57
|
-
* {
|
|
58
|
-
* "event_name": "payment_processed",
|
|
59
|
-
* "timestamp": "2022-03-24T07:15:00Z",
|
|
60
|
-
* "properties": {
|
|
61
|
-
* "amount": 100
|
|
62
|
-
* }
|
|
63
|
-
* },
|
|
64
|
-
* {
|
|
65
|
-
* "event_name": "payment_failed",
|
|
66
|
-
* "timestamp": "2022-03-24T07:15:00Z",
|
|
67
|
-
* "properties": {
|
|
68
|
-
* "amount": 100
|
|
69
|
-
* }
|
|
70
|
-
* }
|
|
71
|
-
* ]
|
|
72
|
-
* }
|
|
73
|
-
* ```
|
|
74
|
-
*
|
|
75
|
-
* ## Request Validation
|
|
76
|
-
*
|
|
77
|
-
* - The `timestamp` of each event reported must fall within the bounds of
|
|
78
|
-
* `timeframe_start` and `timeframe_end`. As with ingestion, all timesta mps must
|
|
79
|
-
* be sent in ISO8601 format with UTC timezone offset.
|
|
80
|
-
* - Orb **does not accept an `idempotency_key`** with each event in this endpoint,
|
|
81
|
-
* since the entirety of the event list must be ingested to ensure consistency.
|
|
82
|
-
* On retryable errors , you should retry the request in its entirety, and assume
|
|
83
|
-
* that the amendment operation has not succeeded until receipt of a `2xx`.
|
|
84
|
-
*
|
|
85
|
-
* - Both `timeframe_start` and `timeframe_end` must be timestamps in the past.
|
|
86
|
-
* Furthermore, Orb will genera lly validate that the `timeframe_start` and
|
|
87
|
-
* `timeframe_end` fall within the customer's _current_ subscription billing pe
|
|
88
|
-
* riod. However, Orb does allow amendments while in the grace period of the
|
|
89
|
-
* previous billing period; in this instance, the timeframe can start before the
|
|
90
|
-
* current period.
|
|
91
|
-
*
|
|
92
|
-
* ## API Limits
|
|
93
|
-
*
|
|
94
|
-
* Note that Orb does not currently enforce a hard rate- limit for API usage or a
|
|
95
|
-
* maximum request payload size. Similar to the event ingestion API, this API is
|
|
96
|
-
* architected for h igh-throughput ingestion. It is also safe to
|
|
97
|
-
* _programmatically_ call this endpoint if your system can automatically dete ct a
|
|
98
|
-
* need for historical amendment.
|
|
99
|
-
*
|
|
100
|
-
* In order to overwrite timeframes with a very large number of events, we suggest
|
|
101
|
-
* using multiple calls with small adjacent (e.g. every hour) timeframes.
|
|
102
|
-
*
|
|
103
|
-
* @deprecated This method will be removed in a future release. Please use the 'events.backfills.create' instead.
|
|
104
|
-
*/
|
|
105
|
-
update(id: string, params: UsageUpdateParams, options?: Core.RequestOptions): Core.APIPromise<UsageUpdateResponse>;
|
|
106
|
-
/**
|
|
107
|
-
* This endpoint is used to amend usage within a timeframe for a customer that has
|
|
108
|
-
* an active subscription.
|
|
109
|
-
*
|
|
110
|
-
* This endpoint will mark _all_ existing events within
|
|
111
|
-
* `[timeframe_start, timeframe_end)` as _ignored_ for billing purposes, and Orb
|
|
112
|
-
* will only use the _new_ events passed in the body of this request as the source
|
|
113
|
-
* of truth for that timeframe moving forwards. Note that a given time period can
|
|
114
|
-
* be amended any number of times, so events can be overwritten in subsequent calls
|
|
115
|
-
* to th is endpoint.
|
|
116
|
-
*
|
|
117
|
-
* This is a powerful and audit-safe mechanism to retroactively change usage data
|
|
118
|
-
* in cases where you need to:
|
|
119
|
-
*
|
|
120
|
-
* - decrease historical usage consumption because of degraded service availability
|
|
121
|
-
* in your systems
|
|
122
|
-
* - account for gaps from your usage reporting mechanism
|
|
123
|
-
* - make point-in-time fixes for specific event records, while retaining the
|
|
124
|
-
* original time of usage and associated metadata. This amendment API is designed
|
|
125
|
-
* with two explicit goals:
|
|
126
|
-
*
|
|
127
|
-
* 1. Amendments are **always audit-safe**. The amendment process will still retain
|
|
128
|
-
* original events in the timeframe, though they will be ignored for billing
|
|
129
|
-
* calculations. For auditing a nd data fidelity purposes, Orb never overwrites
|
|
130
|
-
* or permanently deletes ingested usage data.
|
|
131
|
-
* 2. Amendments always preserve data **consistency**. In other words, either an
|
|
132
|
-
* amendment is fully processed by the system (and the new events for the
|
|
133
|
-
* timeframe are honored rather than the existing ones) or the amendment request
|
|
134
|
-
* fails. To maintain this important property, Orb prevents _partial event
|
|
135
|
-
* ingestion_ on this endpoint.
|
|
136
|
-
*
|
|
137
|
-
* ## Response semantics
|
|
138
|
-
*
|
|
139
|
-
* - Either all events are ingested successfully, or all fail to ingest (returning
|
|
140
|
-
* a `4xx` or `5xx` response code).
|
|
141
|
-
* - Any event that fails schema validation will lead to a `4xx` response. In this
|
|
142
|
-
* case, to maintain data consistency, Orb will not ingest any events and will
|
|
143
|
-
* also not deprecate existing events in the time period.
|
|
144
|
-
* - You can assume that the amendment is successful on receipt of a `2xx`
|
|
145
|
-
* response.While a successful response from this endpoint indicates that the new
|
|
146
|
-
* events have been ingested, updating usage totals happens asynchronously and
|
|
147
|
-
* may be delayed by a few minutes.
|
|
148
|
-
*
|
|
149
|
-
* As emphasized above, Orb will never show an inconsistent state (e.g. in invoice
|
|
150
|
-
* previews or dashboards); either it will show the existing state (before the
|
|
151
|
-
* amendment) or the new state (with new events in the requested timeframe).
|
|
152
|
-
*
|
|
153
|
-
* ## Sample request body
|
|
154
|
-
*
|
|
155
|
-
* ```json
|
|
156
|
-
* {
|
|
157
|
-
* "events": [
|
|
158
|
-
* {
|
|
159
|
-
* "event_name": "payment_processed",
|
|
160
|
-
* "timestamp": "2022-03-24T07:15:00Z",
|
|
161
|
-
* "properties": {
|
|
162
|
-
* "amount": 100
|
|
163
|
-
* }
|
|
164
|
-
* },
|
|
165
|
-
* {
|
|
166
|
-
* "event_name": "payment_failed",
|
|
167
|
-
* "timestamp": "2022-03-24T07:15:00Z",
|
|
168
|
-
* "properties": {
|
|
169
|
-
* "amount": 100
|
|
170
|
-
* }
|
|
171
|
-
* }
|
|
172
|
-
* ]
|
|
173
|
-
* }
|
|
174
|
-
* ```
|
|
175
|
-
*
|
|
176
|
-
* ## Request Validation
|
|
177
|
-
*
|
|
178
|
-
* - The `timestamp` of each event reported must fall within the bounds of
|
|
179
|
-
* `timeframe_start` and `timeframe_end`. As with ingestion, all timesta mps must
|
|
180
|
-
* be sent in ISO8601 format with UTC timezone offset.
|
|
181
|
-
* - Orb **does not accept an `idempotency_key`** with each event in this endpoint,
|
|
182
|
-
* since the entirety of the event list must be ingested to ensure consistency.
|
|
183
|
-
* On retryable errors , you should retry the request in its entirety, and assume
|
|
184
|
-
* that the amendment operation has not succeeded until receipt of a `2xx`.
|
|
185
|
-
*
|
|
186
|
-
* - Both `timeframe_start` and `timeframe_end` must be timestamps in the past.
|
|
187
|
-
* Furthermore, Orb will genera lly validate that the `timeframe_start` and
|
|
188
|
-
* `timeframe_end` fall within the customer's _current_ subscription billing pe
|
|
189
|
-
* riod. However, Orb does allow amendments while in the grace period of the
|
|
190
|
-
* previous billing period; in this instance, the timeframe can start before the
|
|
191
|
-
* current period.
|
|
192
|
-
*
|
|
193
|
-
* ## API Limits
|
|
194
|
-
*
|
|
195
|
-
* Note that Orb does not currently enforce a hard rate- limit for API usage or a
|
|
196
|
-
* maximum request payload size. Similar to the event ingestion API, this API is
|
|
197
|
-
* architected for h igh-throughput ingestion. It is also safe to
|
|
198
|
-
* _programmatically_ call this endpoint if your system can automatically dete ct a
|
|
199
|
-
* need for historical amendment.
|
|
200
|
-
*
|
|
201
|
-
* In order to overwrite timeframes with a very large number of events, we suggest
|
|
202
|
-
* using multiple calls with small adjacent (e.g. every hour) timeframes.
|
|
203
|
-
*
|
|
204
|
-
* @deprecated This method will be removed in a future release. Please use the 'events.backfills.create' instead.
|
|
205
|
-
*/
|
|
206
|
-
updateByExternalId(id: string, params: UsageUpdateByExternalIDParams, options?: Core.RequestOptions): Core.APIPromise<UsageUpdateByExternalIDResponse>;
|
|
207
|
-
}
|
|
208
|
-
export interface UsageUpdateResponse {
|
|
209
|
-
/**
|
|
210
|
-
* An array of strings, corresponding to idempotency_key's marked as duplicates
|
|
211
|
-
* (previously ingested)
|
|
212
|
-
*/
|
|
213
|
-
duplicate: Array<string>;
|
|
214
|
-
/**
|
|
215
|
-
* An array of strings, corresponding to idempotency_key's which were successfully
|
|
216
|
-
* ingested.
|
|
217
|
-
*/
|
|
218
|
-
ingested: Array<string>;
|
|
219
|
-
}
|
|
220
|
-
export interface UsageUpdateByExternalIDResponse {
|
|
221
|
-
/**
|
|
222
|
-
* An array of strings, corresponding to idempotency_key's marked as duplicates
|
|
223
|
-
* (previously ingested)
|
|
224
|
-
*/
|
|
225
|
-
duplicate: Array<string>;
|
|
226
|
-
/**
|
|
227
|
-
* An array of strings, corresponding to idempotency_key's which were successfully
|
|
228
|
-
* ingested.
|
|
229
|
-
*/
|
|
230
|
-
ingested: Array<string>;
|
|
231
|
-
}
|
|
232
|
-
export interface UsageUpdateParams {
|
|
233
|
-
/**
|
|
234
|
-
* Body param: Events to update
|
|
235
|
-
*/
|
|
236
|
-
events: Array<UsageUpdateParams.Event>;
|
|
237
|
-
/**
|
|
238
|
-
* Query param: This bound is exclusive (i.e. events before this timestamp will be
|
|
239
|
-
* updated)
|
|
240
|
-
*/
|
|
241
|
-
timeframe_end?: string;
|
|
242
|
-
/**
|
|
243
|
-
* Query param: This bound is inclusive (i.e. events with this timestamp onward,
|
|
244
|
-
* inclusive will be updated)
|
|
245
|
-
*/
|
|
246
|
-
timeframe_start?: string;
|
|
247
|
-
}
|
|
248
|
-
export declare namespace UsageUpdateParams {
|
|
249
|
-
interface Event {
|
|
250
|
-
/**
|
|
251
|
-
* A name to meaningfully identify the action or event type.
|
|
252
|
-
*/
|
|
253
|
-
event_name: string;
|
|
254
|
-
/**
|
|
255
|
-
* A dictionary of custom properties. Values in this dictionary must be numeric,
|
|
256
|
-
* boolean, or strings. Nested dictionaries are disallowed.
|
|
257
|
-
*/
|
|
258
|
-
properties: unknown;
|
|
259
|
-
/**
|
|
260
|
-
* An ISO 8601 format date with no timezone offset (i.e. UTC). This should
|
|
261
|
-
* represent the time that usage was recorded, and is particularly important to
|
|
262
|
-
* attribute usage to a given billing period.
|
|
263
|
-
*/
|
|
264
|
-
timestamp: string;
|
|
265
|
-
/**
|
|
266
|
-
* The Orb Customer identifier
|
|
267
|
-
*/
|
|
268
|
-
customer_id?: string | null;
|
|
269
|
-
/**
|
|
270
|
-
* An alias for the Orb customer, whose mapping is specified when creating the
|
|
271
|
-
* customer
|
|
272
|
-
*/
|
|
273
|
-
external_customer_id?: string | null;
|
|
274
|
-
}
|
|
275
|
-
}
|
|
276
|
-
export interface UsageUpdateByExternalIDParams {
|
|
277
|
-
/**
|
|
278
|
-
* Body param: Events to update
|
|
279
|
-
*/
|
|
280
|
-
events: Array<UsageUpdateByExternalIDParams.Event>;
|
|
281
|
-
/**
|
|
282
|
-
* Query param: This bound is exclusive (i.e. events before this timestamp will be
|
|
283
|
-
* updated)
|
|
284
|
-
*/
|
|
285
|
-
timeframe_end?: string;
|
|
286
|
-
/**
|
|
287
|
-
* Query param: This bound is inclusive (i.e. events with this timestamp onward,
|
|
288
|
-
* inclusive will be updated)
|
|
289
|
-
*/
|
|
290
|
-
timeframe_start?: string;
|
|
291
|
-
}
|
|
292
|
-
export declare namespace UsageUpdateByExternalIDParams {
|
|
293
|
-
interface Event {
|
|
294
|
-
/**
|
|
295
|
-
* A name to meaningfully identify the action or event type.
|
|
296
|
-
*/
|
|
297
|
-
event_name: string;
|
|
298
|
-
/**
|
|
299
|
-
* A dictionary of custom properties. Values in this dictionary must be numeric,
|
|
300
|
-
* boolean, or strings. Nested dictionaries are disallowed.
|
|
301
|
-
*/
|
|
302
|
-
properties: unknown;
|
|
303
|
-
/**
|
|
304
|
-
* An ISO 8601 format date with no timezone offset (i.e. UTC). This should
|
|
305
|
-
* represent the time that usage was recorded, and is particularly important to
|
|
306
|
-
* attribute usage to a given billing period.
|
|
307
|
-
*/
|
|
308
|
-
timestamp: string;
|
|
309
|
-
/**
|
|
310
|
-
* The Orb Customer identifier
|
|
311
|
-
*/
|
|
312
|
-
customer_id?: string | null;
|
|
313
|
-
/**
|
|
314
|
-
* An alias for the Orb customer, whose mapping is specified when creating the
|
|
315
|
-
* customer
|
|
316
|
-
*/
|
|
317
|
-
external_customer_id?: string | null;
|
|
318
|
-
}
|
|
319
|
-
}
|
|
320
|
-
export declare namespace Usage {
|
|
321
|
-
export import UsageUpdateResponse = UsageAPI.UsageUpdateResponse;
|
|
322
|
-
export import UsageUpdateByExternalIDResponse = UsageAPI.UsageUpdateByExternalIDResponse;
|
|
323
|
-
export import UsageUpdateParams = UsageAPI.UsageUpdateParams;
|
|
324
|
-
export import UsageUpdateByExternalIDParams = UsageAPI.UsageUpdateByExternalIDParams;
|
|
325
|
-
}
|
|
326
|
-
//# sourceMappingURL=usage.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/resources/customers/usage.ts"],"names":[],"mappings":"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"}
|