API documentation
Alert
Customer
- GETList customers
- POSTCreate customer
- GETFetch customer by external ID
- PUTUpdate customer by external ID
- GETFetch customer costs by external ID
- POSTUpdate payment methods from payment provider
- GETFetch customer
- PUTUpdate customer
- DELDelete customer
- GETList balance transactions
- POSTCreate customer balance transaction
- GETFetch customer costs
- POSTUpdate payment methods from payment provider
Credit
- GETFetch customer credit balance by external customer id
- GETFetch customer credits ledger by external ID
- POSTCreate ledger entry by external ID
- GETList top-ups by external ID
- POSTCreate top-up by external ID
- DELDeactivate top-up by external ID
- GETFetch customer credit balance
- GETFetch customer credits ledger
- POSTCreate ledger entry
- GETList top-ups
- POSTCreate top-up
- DELDeactivate top-up
Dimensional Price Group
Event
Invoice
Availability
Plan
Price
Subscription Change
Subscription
- GETList subscriptions
- POSTCreate subscription
- GETFetch subscription
- PUTUpdate subscription
- POSTCancel subscription
- GETFetch subscription costs
- GETFetch subscription schedule
- POSTSchedule plan change
- POSTTrigger phase
- POSTUnschedule subscription cancellation
- POSTUnschedule fixed fee quantity updates
- POSTUnschedule plan change
- POSTUpdate price quantity
- POSTUpdate trial for subscription
- GETFetch subscription usage
Price interval
Update subscription
This endpoint can be used to update the metadata
, net terms
, auto_collection
, invoicing_threshold
,
and default_invoice_memo
properties on a subscription.
curl --request PUT \
--url https://api.withorb.com/v1/subscriptions/{subscription_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"metadata": {},
"default_invoice_memo": "<string>",
"auto_collection": true,
"net_terms": 123,
"invoicing_threshold": "10.00"
}'
{
"metadata": {},
"id": "<string>",
"customer": {
"metadata": {},
"id": "<string>",
"external_customer_id": "<string>",
"name": "<string>",
"email": "<string>",
"timezone": "<string>",
"payment_provider_id": "<string>",
"payment_provider": "quickbooks",
"created_at": "2023-11-07T05:31:56Z",
"shipping_address": {
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>"
},
"billing_address": {
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>"
},
"balance": "<string>",
"currency": "<string>",
"tax_id": {
"country": "AD",
"type": "ad_nrt",
"value": "<string>"
},
"auto_collection": true,
"exempt_from_automated_tax": true,
"email_delivery": true,
"additional_emails": [
"<string>"
],
"portal_url": "<string>",
"accounting_sync_configuration": {
"excluded": true,
"accounting_providers": [
{
"provider_type": "quickbooks",
"external_provider_id": "<string>"
}
]
},
"reporting_configuration": {
"exempt": true
},
"hierarchy": {
"parent": {
"id": "<string>",
"external_customer_id": "<string>"
},
"children": [
{
"id": "<string>",
"external_customer_id": "<string>"
}
]
}
},
"plan": {
"metadata": {},
"id": "<string>",
"name": "<string>",
"description": "<string>",
"maximum_amount": "<string>",
"minimum_amount": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"status": "active",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
},
"product": {
"created_at": "2023-11-07T05:31:56Z",
"id": "<string>",
"name": "<string>"
},
"version": 123,
"trial_config": {
"trial_period": 123,
"trial_period_unit": "days"
},
"plan_phases": [
{
"id": "<string>",
"description": "<string>",
"duration": 123,
"duration_unit": "daily",
"name": "<string>",
"order": 123,
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"minimum_amount": "<string>",
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
}
}
],
"base_plan": {
"id": "m2t5akQeh2obwxeU",
"external_plan_id": "m2t5akQeh2obwxeU",
"name": "Example plan"
},
"base_plan_id": "<string>",
"external_plan_id": "<string>",
"currency": "<string>",
"invoicing_currency": "<string>",
"net_terms": 123,
"default_invoice_memo": "<string>",
"prices": [
{
"metadata": {},
"id": "<string>",
"name": "<string>",
"external_price_id": "<string>",
"price_type": "usage_price",
"model_type": "unit",
"created_at": "2023-11-07T05:31:56Z",
"cadence": "one_time",
"billing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"invoicing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"billable_metric": {
"id": "<string>"
},
"dimensional_price_configuration": {
"dimensional_price_group_id": "<string>",
"dimension_values": [
"<string>"
]
},
"fixed_price_quantity": 123,
"plan_phase_order": 123,
"currency": "<string>",
"conversion_rate": 123,
"item": {
"id": "<string>",
"name": "<string>"
},
"credit_allocation": {
"currency": "<string>",
"allows_rollover": true
},
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"unit_config": {
"unit_amount": "<string>"
}
}
],
"adjustments": [
{
"id": "<string>",
"is_invoice_level": true,
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"reason": "<string>",
"adjustment_type": "usage_discount",
"usage_discount": 123,
"plan_phase_order": 123
}
]
},
"name": "<string>",
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"current_billing_period_start_date": "2023-11-07T05:31:56Z",
"current_billing_period_end_date": "2023-11-07T05:31:56Z",
"status": "active",
"trial_info": {
"end_date": "2023-11-07T05:31:56Z"
},
"active_plan_phase_order": 123,
"fixed_fee_quantity_schedule": [
{
"price_id": "<string>",
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"quantity": 123
}
],
"default_invoice_memo": "<string>",
"auto_collection": true,
"net_terms": 123,
"redeemed_coupon": {
"coupon_id": "<string>",
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z"
},
"billing_cycle_day": 16,
"billing_cycle_anchor_configuration": {
"day": 16,
"month": 6,
"year": 123
},
"invoicing_threshold": "<string>",
"price_intervals": [
{
"id": "<string>",
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"price": {
"metadata": {},
"id": "<string>",
"name": "<string>",
"external_price_id": "<string>",
"price_type": "usage_price",
"model_type": "unit",
"created_at": "2023-11-07T05:31:56Z",
"cadence": "one_time",
"billing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"invoicing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"billable_metric": {
"id": "<string>"
},
"dimensional_price_configuration": {
"dimensional_price_group_id": "<string>",
"dimension_values": [
"<string>"
]
},
"fixed_price_quantity": 123,
"plan_phase_order": 123,
"currency": "<string>",
"conversion_rate": 123,
"item": {
"id": "<string>",
"name": "<string>"
},
"credit_allocation": {
"currency": "<string>",
"allows_rollover": true
},
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"unit_config": {
"unit_amount": "<string>"
}
},
"billing_cycle_day": 123,
"fixed_fee_quantity_transitions": [
{
"price_id": "<string>",
"effective_date": "2023-11-07T05:31:56Z",
"quantity": 123
}
],
"current_billing_period_start_date": "2023-11-07T05:31:56Z",
"current_billing_period_end_date": "2023-11-07T05:31:56Z",
"filter": "<string>",
"usage_customer_ids": [
"<string>"
]
}
],
"adjustment_intervals": [
{
"id": "<string>",
"adjustment": {
"id": "<string>",
"is_invoice_level": true,
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"reason": "<string>",
"adjustment_type": "usage_discount",
"usage_discount": 123,
"plan_phase_order": 123
},
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"applies_to_price_interval_ids": [
"<string>"
]
}
],
"discount_intervals": [
{
"discount_type": "amount",
"amount_discount": "<string>",
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_interval_ids": [
"<string>"
]
}
],
"minimum_intervals": [
{
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_interval_ids": [
"<string>"
],
"minimum_amount": "<string>"
}
],
"maximum_intervals": [
{
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_interval_ids": [
"<string>"
],
"maximum_amount": "<string>"
}
],
"pending_subscription_change": {
"id": "<string>"
}
}
Authorizations
API Keys can be issued in the Orb's web application.
Path Parameters
Body
Response
A subscription represents the purchase of a plan by a customer.
By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition.
Subscriptions also default to beginning of month alignment, which means the first invoice issued for the
subscription will have pro-rated charges between the start_date
and the first of the following month. Subsequent
billing periods will always start and end on a month boundary (e.g. subsequent month starts for monthly billing).
Depending on the plan configuration, any flat recurring fees will be billed either at the beginning (in-advance) or end (in-arrears) of each billing cycle. Plans default to in-advance billing. Usage-based fees are billed in arrears as usage is accumulated. In the normal course of events, you can expect an invoice to contain usage-based charges for the previous period, and a recurring fee for the following period.
Was this page helpful?
curl --request PUT \
--url https://api.withorb.com/v1/subscriptions/{subscription_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"metadata": {},
"default_invoice_memo": "<string>",
"auto_collection": true,
"net_terms": 123,
"invoicing_threshold": "10.00"
}'
{
"metadata": {},
"id": "<string>",
"customer": {
"metadata": {},
"id": "<string>",
"external_customer_id": "<string>",
"name": "<string>",
"email": "<string>",
"timezone": "<string>",
"payment_provider_id": "<string>",
"payment_provider": "quickbooks",
"created_at": "2023-11-07T05:31:56Z",
"shipping_address": {
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>"
},
"billing_address": {
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>"
},
"balance": "<string>",
"currency": "<string>",
"tax_id": {
"country": "AD",
"type": "ad_nrt",
"value": "<string>"
},
"auto_collection": true,
"exempt_from_automated_tax": true,
"email_delivery": true,
"additional_emails": [
"<string>"
],
"portal_url": "<string>",
"accounting_sync_configuration": {
"excluded": true,
"accounting_providers": [
{
"provider_type": "quickbooks",
"external_provider_id": "<string>"
}
]
},
"reporting_configuration": {
"exempt": true
},
"hierarchy": {
"parent": {
"id": "<string>",
"external_customer_id": "<string>"
},
"children": [
{
"id": "<string>",
"external_customer_id": "<string>"
}
]
}
},
"plan": {
"metadata": {},
"id": "<string>",
"name": "<string>",
"description": "<string>",
"maximum_amount": "<string>",
"minimum_amount": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"status": "active",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
},
"product": {
"created_at": "2023-11-07T05:31:56Z",
"id": "<string>",
"name": "<string>"
},
"version": 123,
"trial_config": {
"trial_period": 123,
"trial_period_unit": "days"
},
"plan_phases": [
{
"id": "<string>",
"description": "<string>",
"duration": 123,
"duration_unit": "daily",
"name": "<string>",
"order": 123,
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"minimum_amount": "<string>",
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
}
}
],
"base_plan": {
"id": "m2t5akQeh2obwxeU",
"external_plan_id": "m2t5akQeh2obwxeU",
"name": "Example plan"
},
"base_plan_id": "<string>",
"external_plan_id": "<string>",
"currency": "<string>",
"invoicing_currency": "<string>",
"net_terms": 123,
"default_invoice_memo": "<string>",
"prices": [
{
"metadata": {},
"id": "<string>",
"name": "<string>",
"external_price_id": "<string>",
"price_type": "usage_price",
"model_type": "unit",
"created_at": "2023-11-07T05:31:56Z",
"cadence": "one_time",
"billing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"invoicing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"billable_metric": {
"id": "<string>"
},
"dimensional_price_configuration": {
"dimensional_price_group_id": "<string>",
"dimension_values": [
"<string>"
]
},
"fixed_price_quantity": 123,
"plan_phase_order": 123,
"currency": "<string>",
"conversion_rate": 123,
"item": {
"id": "<string>",
"name": "<string>"
},
"credit_allocation": {
"currency": "<string>",
"allows_rollover": true
},
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"unit_config": {
"unit_amount": "<string>"
}
}
],
"adjustments": [
{
"id": "<string>",
"is_invoice_level": true,
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"reason": "<string>",
"adjustment_type": "usage_discount",
"usage_discount": 123,
"plan_phase_order": 123
}
]
},
"name": "<string>",
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"current_billing_period_start_date": "2023-11-07T05:31:56Z",
"current_billing_period_end_date": "2023-11-07T05:31:56Z",
"status": "active",
"trial_info": {
"end_date": "2023-11-07T05:31:56Z"
},
"active_plan_phase_order": 123,
"fixed_fee_quantity_schedule": [
{
"price_id": "<string>",
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"quantity": 123
}
],
"default_invoice_memo": "<string>",
"auto_collection": true,
"net_terms": 123,
"redeemed_coupon": {
"coupon_id": "<string>",
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z"
},
"billing_cycle_day": 16,
"billing_cycle_anchor_configuration": {
"day": 16,
"month": 6,
"year": 123
},
"invoicing_threshold": "<string>",
"price_intervals": [
{
"id": "<string>",
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"price": {
"metadata": {},
"id": "<string>",
"name": "<string>",
"external_price_id": "<string>",
"price_type": "usage_price",
"model_type": "unit",
"created_at": "2023-11-07T05:31:56Z",
"cadence": "one_time",
"billing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"invoicing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"billable_metric": {
"id": "<string>"
},
"dimensional_price_configuration": {
"dimensional_price_group_id": "<string>",
"dimension_values": [
"<string>"
]
},
"fixed_price_quantity": 123,
"plan_phase_order": 123,
"currency": "<string>",
"conversion_rate": 123,
"item": {
"id": "<string>",
"name": "<string>"
},
"credit_allocation": {
"currency": "<string>",
"allows_rollover": true
},
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"unit_config": {
"unit_amount": "<string>"
}
},
"billing_cycle_day": 123,
"fixed_fee_quantity_transitions": [
{
"price_id": "<string>",
"effective_date": "2023-11-07T05:31:56Z",
"quantity": 123
}
],
"current_billing_period_start_date": "2023-11-07T05:31:56Z",
"current_billing_period_end_date": "2023-11-07T05:31:56Z",
"filter": "<string>",
"usage_customer_ids": [
"<string>"
]
}
],
"adjustment_intervals": [
{
"id": "<string>",
"adjustment": {
"id": "<string>",
"is_invoice_level": true,
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"reason": "<string>",
"adjustment_type": "usage_discount",
"usage_discount": 123,
"plan_phase_order": 123
},
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"applies_to_price_interval_ids": [
"<string>"
]
}
],
"discount_intervals": [
{
"discount_type": "amount",
"amount_discount": "<string>",
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_interval_ids": [
"<string>"
]
}
],
"minimum_intervals": [
{
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_interval_ids": [
"<string>"
],
"minimum_amount": "<string>"
}
],
"maximum_intervals": [
{
"start_date": "2023-11-07T05:31:56Z",
"end_date": "2023-11-07T05:31:56Z",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_interval_ids": [
"<string>"
],
"maximum_amount": "<string>"
}
],
"pending_subscription_change": {
"id": "<string>"
}
}