POST
/
subscriptions
/
{subscription_id}
/
price_intervals
curl --request POST \
  --url https://api.withorb.com/v1/subscriptions/{subscription_id}/price_intervals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "add": [
    {
      "usage_customer_ids": [
        "<string>"
      ],
      "filter": "my_property > 100 AND my_other_property = '\''bar'\''",
      "price_id": "h74gfhdjvn7ujokd",
      "external_price_id": "external_price_id",
      "price": {
        "metadata": {},
        "external_price_id": "<string>",
        "name": "Annual fee",
        "billable_metric_id": "<string>",
        "item_id": "<string>",
        "billed_in_advance": true,
        "fixed_price_quantity": 123,
        "invoice_grouping_key": "<string>",
        "cadence": "annual",
        "billing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "invoicing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "conversion_rate": 123,
        "model_type": "unit",
        "unit_config": {
          "unit_amount": "<string>"
        },
        "currency": "<string>"
      },
      "allocation_price": {
        "currency": "USD",
        "amount": "10.00",
        "cadence": "monthly",
        "expires_at_end_of_cadence": true
      },
      "start_date": "2023-05-01",
      "end_date": "2023-07-10",
      "fixed_fee_quantity_transitions": [
        {
          "quantity": 5,
          "effective_date": "2023-05-01"
        }
      ],
      "discounts": [
        {
          "discount_type": "amount",
          "amount_discount": "10.00"
        }
      ],
      "minimum_amount": "1.23",
      "maximum_amount": "1.23"
    }
  ],
  "edit": [
    {
      "usage_customer_ids": [
        "<string>"
      ],
      "filter": "my_property > 100 AND my_other_property = '\''bar'\''",
      "price_interval_id": "sdfs6wdjvn7ujokd",
      "start_date": "2023-05-01",
      "end_date": "2023-07-10",
      "fixed_fee_quantity_transitions": [
        {
          "quantity": 5,
          "effective_date": "2023-05-01"
        }
      ],
      "billing_cycle_day": 123
    }
  ],
  "add_adjustments": [
    {
      "adjustment": {
        "applies_to_price_ids": [
          "price_1",
          "price_2"
        ],
        "is_invoice_level": true,
        "adjustment_type": "percentage_discount",
        "percentage_discount": 123
      },
      "start_date": "2023-05-01",
      "end_date": "2023-07-10"
    }
  ],
  "edit_adjustments": [
    {
      "adjustment_interval_id": "sdfs6wdjvn7ujokd",
      "start_date": "2023-05-01",
      "end_date": "2023-07-10"
    }
  ],
  "allow_invoice_credit_or_void": true
}'
{
  "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>",
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "minimum": {
      "minimum_amount": "<string>",
      "applies_to_price_ids": [
        "<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>",
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum": {
          "maximum_amount": "<string>",
          "applies_to_price_ids": [
            "<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>",
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "minimum_amount": "<string>",
        "maximum": {
          "maximum_amount": "<string>",
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum_amount": "<string>",
        "unit_config": {
          "unit_amount": "<string>"
        }
      }
    ],
    "adjustments": [
      {
        "id": "<string>",
        "is_invoice_level": true,
        "applies_to_price_ids": [
          "<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",
  "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>",
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "minimum_amount": "<string>",
        "maximum": {
          "maximum_amount": "<string>",
          "applies_to_price_ids": [
            "<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,
        "applies_to_price_ids": [
          "<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",
      "applies_to_price_ids": [
        "<string>"
      ],
      "applies_to_price_interval_ids": [
        "<string>"
      ]
    }
  ],
  "minimum_intervals": [
    {
      "start_date": "2023-11-07T05:31:56Z",
      "end_date": "2023-11-07T05:31:56Z",
      "applies_to_price_ids": [
        "<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",
      "applies_to_price_ids": [
        "<string>"
      ],
      "applies_to_price_interval_ids": [
        "<string>"
      ],
      "maximum_amount": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API Keys can be issued in the Orb's web application.

Path Parameters

​
subscription_id
string
required

Body

application/json
​
add
object[]

A list of price intervals to add to the subscription.

​
edit
object[]

A list of price intervals to edit on the subscription.

​
add_adjustments
object[]

A list of adjustments to add to the subscription.

​
edit_adjustments
object[]

A list of adjustments to edit on the subscription.

​
allow_invoice_credit_or_void
boolean | null
default:
true

If false, this request will fail if it would void an issued invoice or create a credit note. Consider using this as a safety mechanism if you do not expect existing invoices to be changed.

Response

200
application/json
OK
​
metadata
object
required

User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

​
id
string
required
​
customer
object
required

A customer is a buyer of your products, and the other party to the billing relationship.

In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an external_customer_id with your own identifier. See Customer ID Aliases for further information about how these aliases work in Orb.

In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the payment_provider_id and the payment_provider enum field to express this mapping.

A customer also has a timezone (from the standard IANA timezone database), which defaults to your account's timezone. See Timezone localization for information on what this timezone parameter influences within Orb.

​
plan
object
required

The Plan resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the Price resource.

​
start_date
string
required

The date Orb starts billing for this subscription.

​
end_date
string | null
required

The date Orb stops billing for this subscription.

​
created_at
string
required
​
current_billing_period_start_date
string | null
required

The start date of the current billing period. This is an inclusive timestamp; the instant returned is exactly the beginning of the billing period. Set to null if the subscription is not currently active.

​
current_billing_period_end_date
string | null
required

The end of the current billing period. This is an exclusive timestamp, such that the instant returned is not part of the billing period. Set to null for subscriptions that are not currently active.

​
status
enum<string>
required
Available options:
active,
ended,
upcoming
​
trial_info
object
required
​
active_plan_phase_order
integer | null
required

The current plan phase that is active, only if the subscription's plan has phases.

​
fixed_fee_quantity_schedule
object[]
required
​
default_invoice_memo
string | null
required

Determines the default memo on this subscriptions' invoices. Note that if this is not provided, it is determined by the plan configuration.

​
auto_collection
boolean | null
required

Determines whether issued invoices for this subscription will automatically be charged with the saved payment method on the due date. This property defaults to the plan's behavior. If null, defaults to the customer's setting.

​
net_terms
integer
required

Determines the difference between the invoice issue date for subscription invoices as the date that they are due. A value of 0 here represents that the invoice is due on issue, whereas a value of 30 represents that the customer has a month to pay the invoice.

​
redeemed_coupon
object | null
required
​
billing_cycle_day
integer
required

The day of the month on which the billing cycle is anchored. If the maximum number of days in a month is greater than this value, the last day of the month is the billing cycle day (e.g. billing_cycle_day=31 for April means the billing period begins on the 30th.

Required range: 1 < x < 31
​
billing_cycle_anchor_configuration
object
required
​
invoicing_threshold
string | null
required
​
price_intervals
object[]
required

The price intervals for this subscription.

The Price Interval resource represents a period of time for which a price will bill on a subscription. A subscription’s price intervals define its billing behavior.

​
adjustment_intervals
object[]
required

The adjustment intervals for this subscription.

​
discount_intervals
object[]
required

The discount intervals for this subscription.

​
minimum_intervals
object[]
required

The minimum intervals for this subscription.

​
maximum_intervals
object[]
required

The maximum intervals for this subscription.

Was this page helpful?

Fetch subscription usage