Subscription

Create subscription

A subscription represents the purchase of a plan by a customer. The customer is identified by either the customer_id or the external_customer_id, and exactly one of these fields must be provided.

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.

The default configuration for subscriptions in Orb is In-advance billing and Beginning of month alignment (see Subscription for more details).

In order to change the alignment behavior, Orb also supports billing subscriptions on the day of the month they are created. If align_billing_with_subscription_start_date = true is specified, subscriptions have billing cycles that are aligned with their start_date. For example, a subscription that begins on January 15th will have a billing cycle from January 15th to February 15th. Every subsequent billing cycle will continue to start and invoice on the 15th.

If the “day” value is greater than the number of days in the month, the next billing cycle will start at the end of the month. For example, if the start_date is January 31st, the next billing cycle will start on February 28th.

If a customer was created with a currency, Orb only allows subscribing the customer to a plan with a matching invoicing_currency. If the customer does not have a currency set, on subscription creation, we set the customer’s currency to be the invoicing_currency of the plan.

Customize your customer’s subscriptions

Prices and adjustments in a plan can be added, removed, or replaced for the subscription being created. This is useful when a customer has prices that differ from the default prices for a specific plan.

This feature is only available for accounts that have migrated to Subscription Overrides Version 2. You can find your Subscription Overrides Version at the bottom of your Plans page

Adding Prices

To add prices, provide a list of objects with the key add_prices. An object in the list must specify an existing add-on price with a price_id or external_price_id field, or create a new add-on price by including an object with the key price, identical to what would be used in the request body for the create price endpoint. See the Price resource for the specification of different price model configurations possible in this object.

If the plan has phases, each object in the list must include a number with plan_phase_order key to indicate which phase the price should be added to.

An object in the list can specify an optional start_date and optional end_date. This is equivalent to creating a price interval with the add/edit price intervals endpoint. If unspecified, the start or end date of the phase or subscription will be used.

An object in the list can specify an optional minimum_amount, maximum_amount, or discounts. This will create adjustments which apply only to this price.

Additionally, an object in the list can specify an optional reference_id. This ID can be used to reference this price when adding an adjustment in the same API call. However the ID is transient and cannot be used to refer to the price in future API calls.

Removing Prices

To remove prices, provide a list of objects with the key remove_prices. An object in the list must specify a plan price with either a price_id or external_price_id field.

Replacing Prices

To replace prices, provide a list of objects with the key replace_prices. An object in the list must specify a plan price to replace with the replaces_price_id key, and it must specify a price to replace it with by either referencing an existing add-on price with a price_id or external_price_id field, or by creating a new add-on price by including an object with the key price, identical to what would be used in the request body for the create price endpoint. See the Price resource for the specification of different price model configurations possible in this object.

For fixed fees, an object in the list can supply a fixed_price_quantity instead of a price, price_id, or external_price_id field. This will update only the quantity for the price, similar to the Update price quantity endpoint.

The replacement price will have the same phase, if applicable, and the same start and end dates as the price it replaces.

An object in the list can specify an optional minimum_amount, maximum_amount, or discounts. This will create adjustments which apply only to this price.

Additionally, an object in the list can specify an optional reference_id. This ID can be used to reference the replacement price when adding an adjustment in the same API call. However the ID is transient and cannot be used to refer to the price in future API calls.

Adding adjustments

To add adjustments, provide a list of objects with the key add_adjustments. An object in the list must include an object with the key adjustment, identical to the adjustment object in the add/edit price intervals endpoint.

If the plan has phases, each object in the list must include a number with plan_phase_order key to indicate which phase the adjustment should be added to.

An object in the list can specify an optional start_date and optional end_date. If unspecified, the start or end date of the phase or subscription will be used.

Removing adjustments

To remove adjustments, provide a list of objects with the key remove_adjustments. An object in the list must include a key, adjustment_id, with the ID of the adjustment to be removed.

Replacing adjustments

To replace adjustments, provide a list of objects with the key replace_adjustments. An object in the list must specify a plan adjustment to replace with the replaces_adjustment_id key, and it must specify an adjustment to replace it with by including an object with the key adjustment, identical to the adjustment object in the add/edit price intervals endpoint.

The replacement adjustment will have the same phase, if applicable, and the same start and end dates as the adjustment it replaces.

Price overrides (DEPRECATED)

Price overrides are being phased out in favor adding/removing/replacing prices. (See Customize your customer’s subscriptions)

Price overrides are used to update some or all prices in a plan for the specific subscription being created. This is useful when a new customer has negotiated a rate that is unique to the customer.

To override prices, provide a list of objects with the key price_overrides. The price object in the list of overrides is expected to contain the existing price id, the model_type and configuration. (See the Price resource for the specification of different price model configurations.) The numerical values can be updated, but the billable metric, cadence, type, and name of a price can not be overridden.

Maximums and Minimums

Minimums and maximums, much like price overrides, can be useful when a new customer has negotiated a new or different minimum or maximum spend cap than the default for a given price. If one exists for a price and null is provided for the minimum/maximum override on creation, then there will be no minimum/maximum on the new subscription. If no value is provided, then the default price maximum or minimum is used.

To add a minimum for a specific price, add minimum_amount to the specific price in the price_overrides object.

To add a maximum for a specific price, add maximum_amount to the specific price in the price_overrides object.

Minimum override example

Price minimum override example:

{
  ...
  "id": "price_id",
  "model_type": "unit",
  "unit_config": {
    "unit_amount": "0.50"
  },
  "minimum_amount": "100.00"
  ...
}

Removing an existing minimum example

{
  ...
  "id": "price_id",
  "model_type": "unit",
  "unit_config": {
    "unit_amount": "0.50"
  },
  "minimum_amount": null
  ...
}

Discounts

Discounts, like price overrides, can be useful when a new customer has negotiated a new or different discount than the default for a price. If a discount exists for a price and a null discount is provided on creation, then there will be no discount on the new subscription.

To add a discount for a specific price, add discount to the price in the price_overrides object. Discount should be a dictionary of the format:

{
  "discount_type": "amount" | "percentage" | "usage",
  "amount_discount": string,
  "percentage_discount": string,
  "usage_discount": string
}

where either amount_discount, percentage_discount, or usage_discount is provided.

Price discount example

{
  ...
  "id": "price_id",
  "model_type": "unit",
  "unit_config": {
    "unit_amount": "0.50"
  },
  "discount": {"discount_type": "amount", "amount_discount": "175"},
}

Removing an existing discount example

{
  "customer_id": "customer_id",
  "plan_id": "plan_id",
  "discount": null,
  "price_overrides": [ ... ]
  ...
}

Threshold Billing

Orb supports invoicing for a subscription when a preconfigured usage threshold is hit. To enable threshold billing, pass in an invoicing_threshold, which is specified in the subscription’s invoicing currency, when creating a subscription. E.g. pass in 10.00 to issue an invoice when usage amounts hit $10.00 for a subscription that invoices in USD.

POST

subscriptions

Copy
curl --request POST \
  --url https://api.withorb.com/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "usage_customer_ids": [
    "<string>"
  ],
  "filter": "my_property > 100 AND my_other_property = '\''bar'\''",
  "metadata": {},
  "plan_id": "ZMwNQefe7J3ecf7W",
  "external_plan_id": "ZMwNQefe7J3ecf7W",
  "price_overrides": [
    "<any>"
  ],
  "per_credit_overage_amount": 123,
  "credits_overage_rate": 123,
  "trial_duration_days": 500000,
  "net_terms": 123,
  "auto_collection": true,
  "default_invoice_memo": "<string>",
  "coupon_redemption_code": "<string>",
  "invoicing_threshold": "10.00",
  "initial_phase_order": 2,
  "add_prices": [
    {
      "price_id": "h74gfhdjvn7ujokd",
      "external_price_id": "external_price_id",
      "price": {
        "metadata": {},
        "external_price_id": "<string>",
        "name": "Annual fee",
        "dimensional_price_configuration": {
          "dimensional_price_group_id": "<string>",
          "external_dimensional_price_group_id": "<string>",
          "dimension_values": [
            "<string>"
          ]
        },
        "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>",
        "reference_id": "<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",
      "plan_phase_order": 123,
      "minimum_amount": "1.23",
      "maximum_amount": "1.23",
      "discounts": [
        {
          "discount_type": "percentage",
          "percentage_discount": 0.15,
          "usage_discount": 123,
          "amount_discount": "<string>"
        }
      ]
    }
  ],
  "remove_prices": [
    {
      "price_id": "h74gfhdjvn7ujokd",
      "external_price_id": "external_price_id"
    }
  ],
  "replace_prices": [
    {
      "price_id": "h74gfhdjvn7ujokd",
      "external_price_id": "external_price_id",
      "price": {
        "metadata": {},
        "external_price_id": "<string>",
        "name": "Annual fee",
        "dimensional_price_configuration": {
          "dimensional_price_group_id": "<string>",
          "external_dimensional_price_group_id": "<string>",
          "dimension_values": [
            "<string>"
          ]
        },
        "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>",
        "reference_id": "<string>"
      },
      "allocation_price": {
        "currency": "USD",
        "amount": "10.00",
        "cadence": "monthly",
        "expires_at_end_of_cadence": true
      },
      "fixed_price_quantity": 2,
      "replaces_price_id": "<string>",
      "minimum_amount": "1.23",
      "maximum_amount": "1.23",
      "discounts": [
        {
          "discount_type": "percentage",
          "percentage_discount": 0.15,
          "usage_discount": 123,
          "amount_discount": "<string>"
        }
      ]
    }
  ],
  "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",
      "plan_phase_order": 123
    }
  ],
  "remove_adjustments": [
    {
      "adjustment_id": "h74gfhdjvn7ujokd"
    }
  ],
  "replace_adjustments": [
    {
      "adjustment": {
        "applies_to_price_ids": [
          "price_1",
          "price_2"
        ],
        "is_invoice_level": true,
        "adjustment_type": "percentage_discount",
        "percentage_discount": 123
      },
      "replaces_adjustment_id": "<string>"
    }
  ],
  "customer_id": "<string>",
  "external_customer_id": "<string>",
  "currency": "<string>",
  "name": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "plan_version_number": 123,
  "external_marketplace": "google",
  "external_marketplace_reporting_id": "<string>",
  "aws_region": "<string>",
  "align_billing_with_subscription_start_date": false,
  "billing_cycle_anchor_configuration": {
    "day": 16,
    "month": 6,
    "year": 123
  }
}'

Copy
{
  "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>"
  },
  "changed_resources": {
    "created_credit_notes": [
      {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "voided_at": "2023-11-07T05:31:56Z",
        "credit_note_number": "<string>",
        "invoice_id": "<string>",
        "memo": "<string>",
        "reason": "Duplicate",
        "type": "refund",
        "subtotal": "<string>",
        "total": "<string>",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "credit_note_pdf": "<string>",
        "minimum_amount_refunded": "<string>",
        "discounts": [
          {
            "discount_type": "percentage",
            "percentage_discount": 123,
            "amount_applied": "<string>",
            "reason": "<string>",
            "applies_to_prices": [
              {
                "id": "<string>",
                "name": "<string>"
              }
            ]
          }
        ],
        "maximum_amount_adjustment": {
          "discount_type": "percentage",
          "percentage_discount": 123,
          "amount_applied": "<string>",
          "reason": "<string>",
          "applies_to_prices": [
            {
              "id": "<string>",
              "name": "<string>"
            }
          ]
        },
        "line_items": [
          {
            "id": "<string>",
            "name": "<string>",
            "subtotal": "<string>",
            "amount": "<string>",
            "quantity": 123,
            "discounts": [
              {
                "id": "<string>",
                "discount_type": "percentage",
                "percentage_discount": 123,
                "amount_discount": "<string>",
                "amount_applied": "<string>",
                "reason": "<string>",
                "applies_to_price_ids": [
                  "<string>"
                ]
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "item_id": "<string>"
          }
        ]
      }
    ],
    "voided_credit_notes": [
      {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "voided_at": "2023-11-07T05:31:56Z",
        "credit_note_number": "<string>",
        "invoice_id": "<string>",
        "memo": "<string>",
        "reason": "Duplicate",
        "type": "refund",
        "subtotal": "<string>",
        "total": "<string>",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "credit_note_pdf": "<string>",
        "minimum_amount_refunded": "<string>",
        "discounts": [
          {
            "discount_type": "percentage",
            "percentage_discount": 123,
            "amount_applied": "<string>",
            "reason": "<string>",
            "applies_to_prices": [
              {
                "id": "<string>",
                "name": "<string>"
              }
            ]
          }
        ],
        "maximum_amount_adjustment": {
          "discount_type": "percentage",
          "percentage_discount": 123,
          "amount_applied": "<string>",
          "reason": "<string>",
          "applies_to_prices": [
            {
              "id": "<string>",
              "name": "<string>"
            }
          ]
        },
        "line_items": [
          {
            "id": "<string>",
            "name": "<string>",
            "subtotal": "<string>",
            "amount": "<string>",
            "quantity": 123,
            "discounts": [
              {
                "id": "<string>",
                "discount_type": "percentage",
                "percentage_discount": 123,
                "amount_discount": "<string>",
                "amount_applied": "<string>",
                "reason": "<string>",
                "applies_to_price_ids": [
                  "<string>"
                ]
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "item_id": "<string>"
          }
        ]
      }
    ],
    "created_invoices": [
      {
        "metadata": {},
        "voided_at": "2023-11-07T05:31:56Z",
        "paid_at": "2023-11-07T05:31:56Z",
        "issued_at": "2023-11-07T05:31:56Z",
        "scheduled_issue_at": "2023-11-07T05:31:56Z",
        "auto_collection": {
          "next_attempt_at": "2023-11-07T05:31:56Z",
          "previously_attempted_at": "2023-11-07T05:31:56Z",
          "enabled": true,
          "num_attempts": 123
        },
        "issue_failed_at": "2023-11-07T05:31:56Z",
        "sync_failed_at": "2023-11-07T05:31:56Z",
        "payment_failed_at": "2023-11-07T05:31:56Z",
        "payment_started_at": "2023-11-07T05:31:56Z",
        "amount_due": "8.00",
        "created_at": "2022-05-01T07:01:31+00:00",
        "currency": "USD",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "discount": "<any>",
        "discounts": [
          {
            "discount_type": "percentage",
            "applies_to_price_ids": [
              "h74gfhdjvn7ujokd",
              "7hfgtgjnbvc3ujkl"
            ],
            "reason": "<string>",
            "percentage_discount": 0.15
          }
        ],
        "due_date": "2022-05-30T07:00:00+00:00",
        "id": "<string>",
        "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
        "invoice_number": "JYEFHK-00001",
        "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>",
        "line_items": [
          {
            "amount": "7.00",
            "discount": {
              "discount_type": "percentage",
              "applies_to_price_ids": [
                "h74gfhdjvn7ujokd",
                "7hfgtgjnbvc3ujkl"
              ],
              "reason": "<string>",
              "percentage_discount": 0.15
            },
            "end_date": "2022-02-01T08:00:00+00:00",
            "grouping": "<string>",
            "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>",
            "adjustments": [
              {
                "id": "<string>",
                "is_invoice_level": true,
                "filters": [
                  {
                    "field": "price_id",
                    "operator": "includes",
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "reason": "<string>",
                "adjustment_type": "usage_discount",
                "usage_discount": 123,
                "amount": "<string>"
              }
            ],
            "name": "Fixed Fee",
            "quantity": 1,
            "start_date": "2022-02-01T08:00:00+00:00",
            "subtotal": "9.00",
            "adjusted_subtotal": "5.00",
            "credits_applied": "6.00",
            "partially_invoiced_amount": "4.00",
            "sub_line_items": [
              {
                "amount": "9.00",
                "name": "Tier One",
                "quantity": 5,
                "grouping": {
                  "key": "region",
                  "value": "west"
                },
                "type": "matrix",
                "matrix_config": {
                  "dimension_values": [
                    "<string>"
                  ]
                }
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "id": "<string>",
            "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>"
              }
            },
            "usage_customer_ids": [
              "<string>"
            ],
            "filter": "<string>"
          }
        ],
        "subscription": {
          "id": "VDGsT23osdLb84KD"
        },
        "subtotal": "8.00",
        "total": "8.00",
        "customer_balance_transactions": [
          {
            "id": "cgZa3SXcsPTVyC4Y",
            "created_at": "2022-05-01T07:01:31+00:00",
            "starting_balance": "33.00",
            "ending_balance": "22.00",
            "amount": "11.00",
            "action": "applied_to_invoice",
            "description": "An optional description",
            "invoice": {
              "id": "gXcsPTVyC4YZa3Sc"
            },
            "type": "increment",
            "credit_note": {
              "id": "<string>"
            }
          }
        ],
        "status": "issued",
        "invoice_source": "subscription",
        "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>"
        },
        "hosted_invoice_url": "<string>",
        "will_auto_issue": true,
        "eligible_to_issue_at": "2023-11-07T05:31:56Z",
        "customer_tax_id": {
          "country": "AD",
          "type": "ad_nrt",
          "value": "<string>"
        },
        "memo": "<string>",
        "credit_notes": [
          {
            "id": "<string>",
            "credit_note_number": "<string>",
            "reason": "<string>",
            "total": "<string>",
            "voided_at": "2022-05-01T07:01:31+00:00",
            "type": "<string>",
            "memo": "<string>"
          }
        ],
        "payment_attempts": [
          {
            "id": "<string>",
            "payment_provider": "stripe",
            "payment_provider_id": "<string>",
            "amount": "<string>",
            "succeeded": true,
            "created_at": "2023-11-07T05:31:56Z"
          }
        ],
        "invoice_date": "2022-05-01T07:00:00+00:00"
      }
    ],
    "voided_invoices": [
      {
        "metadata": {},
        "voided_at": "2023-11-07T05:31:56Z",
        "paid_at": "2023-11-07T05:31:56Z",
        "issued_at": "2023-11-07T05:31:56Z",
        "scheduled_issue_at": "2023-11-07T05:31:56Z",
        "auto_collection": {
          "next_attempt_at": "2023-11-07T05:31:56Z",
          "previously_attempted_at": "2023-11-07T05:31:56Z",
          "enabled": true,
          "num_attempts": 123
        },
        "issue_failed_at": "2023-11-07T05:31:56Z",
        "sync_failed_at": "2023-11-07T05:31:56Z",
        "payment_failed_at": "2023-11-07T05:31:56Z",
        "payment_started_at": "2023-11-07T05:31:56Z",
        "amount_due": "8.00",
        "created_at": "2022-05-01T07:01:31+00:00",
        "currency": "USD",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "discount": "<any>",
        "discounts": [
          {
            "discount_type": "percentage",
            "applies_to_price_ids": [
              "h74gfhdjvn7ujokd",
              "7hfgtgjnbvc3ujkl"
            ],
            "reason": "<string>",
            "percentage_discount": 0.15
          }
        ],
        "due_date": "2022-05-30T07:00:00+00:00",
        "id": "<string>",
        "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
        "invoice_number": "JYEFHK-00001",
        "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>",
        "line_items": [
          {
            "amount": "7.00",
            "discount": {
              "discount_type": "percentage",
              "applies_to_price_ids": [
                "h74gfhdjvn7ujokd",
                "7hfgtgjnbvc3ujkl"
              ],
              "reason": "<string>",
              "percentage_discount": 0.15
            },
            "end_date": "2022-02-01T08:00:00+00:00",
            "grouping": "<string>",
            "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>",
            "adjustments": [
              {
                "id": "<string>",
                "is_invoice_level": true,
                "filters": [
                  {
                    "field": "price_id",
                    "operator": "includes",
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "reason": "<string>",
                "adjustment_type": "usage_discount",
                "usage_discount": 123,
                "amount": "<string>"
              }
            ],
            "name": "Fixed Fee",
            "quantity": 1,
            "start_date": "2022-02-01T08:00:00+00:00",
            "subtotal": "9.00",
            "adjusted_subtotal": "5.00",
            "credits_applied": "6.00",
            "partially_invoiced_amount": "4.00",
            "sub_line_items": [
              {
                "amount": "9.00",
                "name": "Tier One",
                "quantity": 5,
                "grouping": {
                  "key": "region",
                  "value": "west"
                },
                "type": "matrix",
                "matrix_config": {
                  "dimension_values": [
                    "<string>"
                  ]
                }
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "id": "<string>",
            "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>"
              }
            },
            "usage_customer_ids": [
              "<string>"
            ],
            "filter": "<string>"
          }
        ],
        "subscription": {
          "id": "VDGsT23osdLb84KD"
        },
        "subtotal": "8.00",
        "total": "8.00",
        "customer_balance_transactions": [
          {
            "id": "cgZa3SXcsPTVyC4Y",
            "created_at": "2022-05-01T07:01:31+00:00",
            "starting_balance": "33.00",
            "ending_balance": "22.00",
            "amount": "11.00",
            "action": "applied_to_invoice",
            "description": "An optional description",
            "invoice": {
              "id": "gXcsPTVyC4YZa3Sc"
            },
            "type": "increment",
            "credit_note": {
              "id": "<string>"
            }
          }
        ],
        "status": "issued",
        "invoice_source": "subscription",
        "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>"
        },
        "hosted_invoice_url": "<string>",
        "will_auto_issue": true,
        "eligible_to_issue_at": "2023-11-07T05:31:56Z",
        "customer_tax_id": {
          "country": "AD",
          "type": "ad_nrt",
          "value": "<string>"
        },
        "memo": "<string>",
        "credit_notes": [
          {
            "id": "<string>",
            "credit_note_number": "<string>",
            "reason": "<string>",
            "total": "<string>",
            "voided_at": "2022-05-01T07:01:31+00:00",
            "type": "<string>",
            "memo": "<string>"
          }
        ],
        "payment_attempts": [
          {
            "id": "<string>",
            "payment_provider": "stripe",
            "payment_provider_id": "<string>",
            "amount": "<string>",
            "succeeded": true,
            "created_at": "2023-11-07T05:31:56Z"
          }
        ],
        "invoice_date": "2022-05-01T07:00:00+00:00"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

usage_customer_ids

string[] | null

A list of customer IDs whose usage events will be aggregated and billed under this subscription. By default, a subscription only considers usage events associated with its attached customer's customer_id. When usage_customer_ids is provided, the subscription includes usage events from the specified customers only. Provided usage_customer_ids must be either the customer for this subscription itself, or any of that customer's children.

filter

string | null

An additional filter to apply to usage queries. This filter must be expressed as a boolean computed property. If null, usage queries will not include any additional filter.

Examples:

"my_property > 100 AND my_other_property = 'bar'"

"my_property = 'foo'"

metadata

object | null

User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

plan_id

string | null

The plan that the given subscription should be switched to. Note that either this property or external_plan_id must be specified.

Examples:

"ZMwNQefe7J3ecf7W"

external_plan_id

string | null

The external_plan_id of the plan that the given subscription should be switched to. Note that either this property or plan_id must be specified.

Examples:

"ZMwNQefe7J3ecf7W"

price_overrides

any[] | null

deprecated

Optionally provide a list of overrides for prices on the plan

per_credit_overage_amount

number | null

deprecated

credits_overage_rate

number | null

deprecated

trial_duration_days

integer | null

The duration of the trial period in days. If not provided, this defaults to the value specified in the plan. If 0 is provided, the trial on the plan will be skipped.

Required range: 0 <= x < 1000000

net_terms

integer | null

The net terms determines the difference between the invoice date and the issue date for the invoice. If you intend the invoice to be due on issue, set this to 0. If not provided, this defaults to the value specified in the plan.

auto_collection

boolean | null

Determines whether issued invoices for this subscription will automatically be charged with the saved payment method on the due date. If not specified, this defaults to the behavior configured for this customer.

default_invoice_memo

string | null

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

coupon_redemption_code

string | null

Redemption code to be used for this subscription. If the coupon cannot be found by its redemption code, or cannot be redeemed, an error response will be returned and the subscription creation or plan change will not be scheduled.

invoicing_threshold

string | null

When this subscription's accrued usage reaches this threshold, an invoice will be issued for the subscription. If not specified, invoices will only be issued at the end of the billing period.

Examples:

"10.00"

initial_phase_order

integer | null

The phase of the plan to start with

Examples:

2

add_prices

object[] | null

Additional prices to be added to the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

remove_prices

object[] | null

Plan prices to be removed from the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

replace_prices

object[] | null

Plan prices to be replaced with additional prices on the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

add_adjustments

object[] | null

Additional adjustments to be added to the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

remove_adjustments

object[] | null

Plan adjustments to be removed from the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

replace_adjustments

object[] | null

Plan adjustments to be replaced with additional adjustments on the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)

customer_id

string | null

external_customer_id

string | null

currency

string | null

The currency to use for the subscription. If not specified, the invoicing currency for the plan will be used.

name

string | null

The name to use for the subscription. If not specified, the plan name will be used.

start_date

string | null

end_date

string | null

plan_version_number

integer | null

Specifies which version of the plan to subscribe to. If null, the default version will be used.

external_marketplace

enum<string> | null

deprecated

Available options:

google,

aws,

azure

external_marketplace_reporting_id

string | null

deprecated

aws_region

string | null

deprecated

align_billing_with_subscription_start_date

boolean

default:false

billing_cycle_anchor_configuration

object | null

Response

201

application/json

Created

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.

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 | null

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.

name

string

required

The name of the subscription.

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 sorted by the start_date of the adjustment interval.

discount_intervals

object[]

required

The discount intervals for this subscription sorted by the start_date.

minimum_intervals

object[]

required

The minimum intervals for this subscription sorted by the start_date.

maximum_intervals

object[]

required

The maximum intervals for this subscription sorted by the start_date.

pending_subscription_change

object | null

required

A pending subscription change if one exists on this subscription.

changed_resources

object | null

The resources that were changed as part of this operation. Only present when fetched through the subscription changes API or if the include_changed_resources parameter was passed in the request.

List subscriptions Fetch subscription

Copy
curl --request POST \
  --url https://api.withorb.com/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "usage_customer_ids": [
    "<string>"
  ],
  "filter": "my_property > 100 AND my_other_property = '\''bar'\''",
  "metadata": {},
  "plan_id": "ZMwNQefe7J3ecf7W",
  "external_plan_id": "ZMwNQefe7J3ecf7W",
  "price_overrides": [
    "<any>"
  ],
  "per_credit_overage_amount": 123,
  "credits_overage_rate": 123,
  "trial_duration_days": 500000,
  "net_terms": 123,
  "auto_collection": true,
  "default_invoice_memo": "<string>",
  "coupon_redemption_code": "<string>",
  "invoicing_threshold": "10.00",
  "initial_phase_order": 2,
  "add_prices": [
    {
      "price_id": "h74gfhdjvn7ujokd",
      "external_price_id": "external_price_id",
      "price": {
        "metadata": {},
        "external_price_id": "<string>",
        "name": "Annual fee",
        "dimensional_price_configuration": {
          "dimensional_price_group_id": "<string>",
          "external_dimensional_price_group_id": "<string>",
          "dimension_values": [
            "<string>"
          ]
        },
        "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>",
        "reference_id": "<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",
      "plan_phase_order": 123,
      "minimum_amount": "1.23",
      "maximum_amount": "1.23",
      "discounts": [
        {
          "discount_type": "percentage",
          "percentage_discount": 0.15,
          "usage_discount": 123,
          "amount_discount": "<string>"
        }
      ]
    }
  ],
  "remove_prices": [
    {
      "price_id": "h74gfhdjvn7ujokd",
      "external_price_id": "external_price_id"
    }
  ],
  "replace_prices": [
    {
      "price_id": "h74gfhdjvn7ujokd",
      "external_price_id": "external_price_id",
      "price": {
        "metadata": {},
        "external_price_id": "<string>",
        "name": "Annual fee",
        "dimensional_price_configuration": {
          "dimensional_price_group_id": "<string>",
          "external_dimensional_price_group_id": "<string>",
          "dimension_values": [
            "<string>"
          ]
        },
        "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>",
        "reference_id": "<string>"
      },
      "allocation_price": {
        "currency": "USD",
        "amount": "10.00",
        "cadence": "monthly",
        "expires_at_end_of_cadence": true
      },
      "fixed_price_quantity": 2,
      "replaces_price_id": "<string>",
      "minimum_amount": "1.23",
      "maximum_amount": "1.23",
      "discounts": [
        {
          "discount_type": "percentage",
          "percentage_discount": 0.15,
          "usage_discount": 123,
          "amount_discount": "<string>"
        }
      ]
    }
  ],
  "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",
      "plan_phase_order": 123
    }
  ],
  "remove_adjustments": [
    {
      "adjustment_id": "h74gfhdjvn7ujokd"
    }
  ],
  "replace_adjustments": [
    {
      "adjustment": {
        "applies_to_price_ids": [
          "price_1",
          "price_2"
        ],
        "is_invoice_level": true,
        "adjustment_type": "percentage_discount",
        "percentage_discount": 123
      },
      "replaces_adjustment_id": "<string>"
    }
  ],
  "customer_id": "<string>",
  "external_customer_id": "<string>",
  "currency": "<string>",
  "name": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "plan_version_number": 123,
  "external_marketplace": "google",
  "external_marketplace_reporting_id": "<string>",
  "aws_region": "<string>",
  "align_billing_with_subscription_start_date": false,
  "billing_cycle_anchor_configuration": {
    "day": 16,
    "month": 6,
    "year": 123
  }
}'

Copy
{
  "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>"
  },
  "changed_resources": {
    "created_credit_notes": [
      {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "voided_at": "2023-11-07T05:31:56Z",
        "credit_note_number": "<string>",
        "invoice_id": "<string>",
        "memo": "<string>",
        "reason": "Duplicate",
        "type": "refund",
        "subtotal": "<string>",
        "total": "<string>",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "credit_note_pdf": "<string>",
        "minimum_amount_refunded": "<string>",
        "discounts": [
          {
            "discount_type": "percentage",
            "percentage_discount": 123,
            "amount_applied": "<string>",
            "reason": "<string>",
            "applies_to_prices": [
              {
                "id": "<string>",
                "name": "<string>"
              }
            ]
          }
        ],
        "maximum_amount_adjustment": {
          "discount_type": "percentage",
          "percentage_discount": 123,
          "amount_applied": "<string>",
          "reason": "<string>",
          "applies_to_prices": [
            {
              "id": "<string>",
              "name": "<string>"
            }
          ]
        },
        "line_items": [
          {
            "id": "<string>",
            "name": "<string>",
            "subtotal": "<string>",
            "amount": "<string>",
            "quantity": 123,
            "discounts": [
              {
                "id": "<string>",
                "discount_type": "percentage",
                "percentage_discount": 123,
                "amount_discount": "<string>",
                "amount_applied": "<string>",
                "reason": "<string>",
                "applies_to_price_ids": [
                  "<string>"
                ]
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "item_id": "<string>"
          }
        ]
      }
    ],
    "voided_credit_notes": [
      {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "voided_at": "2023-11-07T05:31:56Z",
        "credit_note_number": "<string>",
        "invoice_id": "<string>",
        "memo": "<string>",
        "reason": "Duplicate",
        "type": "refund",
        "subtotal": "<string>",
        "total": "<string>",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "credit_note_pdf": "<string>",
        "minimum_amount_refunded": "<string>",
        "discounts": [
          {
            "discount_type": "percentage",
            "percentage_discount": 123,
            "amount_applied": "<string>",
            "reason": "<string>",
            "applies_to_prices": [
              {
                "id": "<string>",
                "name": "<string>"
              }
            ]
          }
        ],
        "maximum_amount_adjustment": {
          "discount_type": "percentage",
          "percentage_discount": 123,
          "amount_applied": "<string>",
          "reason": "<string>",
          "applies_to_prices": [
            {
              "id": "<string>",
              "name": "<string>"
            }
          ]
        },
        "line_items": [
          {
            "id": "<string>",
            "name": "<string>",
            "subtotal": "<string>",
            "amount": "<string>",
            "quantity": 123,
            "discounts": [
              {
                "id": "<string>",
                "discount_type": "percentage",
                "percentage_discount": 123,
                "amount_discount": "<string>",
                "amount_applied": "<string>",
                "reason": "<string>",
                "applies_to_price_ids": [
                  "<string>"
                ]
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "item_id": "<string>"
          }
        ]
      }
    ],
    "created_invoices": [
      {
        "metadata": {},
        "voided_at": "2023-11-07T05:31:56Z",
        "paid_at": "2023-11-07T05:31:56Z",
        "issued_at": "2023-11-07T05:31:56Z",
        "scheduled_issue_at": "2023-11-07T05:31:56Z",
        "auto_collection": {
          "next_attempt_at": "2023-11-07T05:31:56Z",
          "previously_attempted_at": "2023-11-07T05:31:56Z",
          "enabled": true,
          "num_attempts": 123
        },
        "issue_failed_at": "2023-11-07T05:31:56Z",
        "sync_failed_at": "2023-11-07T05:31:56Z",
        "payment_failed_at": "2023-11-07T05:31:56Z",
        "payment_started_at": "2023-11-07T05:31:56Z",
        "amount_due": "8.00",
        "created_at": "2022-05-01T07:01:31+00:00",
        "currency": "USD",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "discount": "<any>",
        "discounts": [
          {
            "discount_type": "percentage",
            "applies_to_price_ids": [
              "h74gfhdjvn7ujokd",
              "7hfgtgjnbvc3ujkl"
            ],
            "reason": "<string>",
            "percentage_discount": 0.15
          }
        ],
        "due_date": "2022-05-30T07:00:00+00:00",
        "id": "<string>",
        "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
        "invoice_number": "JYEFHK-00001",
        "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>",
        "line_items": [
          {
            "amount": "7.00",
            "discount": {
              "discount_type": "percentage",
              "applies_to_price_ids": [
                "h74gfhdjvn7ujokd",
                "7hfgtgjnbvc3ujkl"
              ],
              "reason": "<string>",
              "percentage_discount": 0.15
            },
            "end_date": "2022-02-01T08:00:00+00:00",
            "grouping": "<string>",
            "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>",
            "adjustments": [
              {
                "id": "<string>",
                "is_invoice_level": true,
                "filters": [
                  {
                    "field": "price_id",
                    "operator": "includes",
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "reason": "<string>",
                "adjustment_type": "usage_discount",
                "usage_discount": 123,
                "amount": "<string>"
              }
            ],
            "name": "Fixed Fee",
            "quantity": 1,
            "start_date": "2022-02-01T08:00:00+00:00",
            "subtotal": "9.00",
            "adjusted_subtotal": "5.00",
            "credits_applied": "6.00",
            "partially_invoiced_amount": "4.00",
            "sub_line_items": [
              {
                "amount": "9.00",
                "name": "Tier One",
                "quantity": 5,
                "grouping": {
                  "key": "region",
                  "value": "west"
                },
                "type": "matrix",
                "matrix_config": {
                  "dimension_values": [
                    "<string>"
                  ]
                }
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "id": "<string>",
            "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>"
              }
            },
            "usage_customer_ids": [
              "<string>"
            ],
            "filter": "<string>"
          }
        ],
        "subscription": {
          "id": "VDGsT23osdLb84KD"
        },
        "subtotal": "8.00",
        "total": "8.00",
        "customer_balance_transactions": [
          {
            "id": "cgZa3SXcsPTVyC4Y",
            "created_at": "2022-05-01T07:01:31+00:00",
            "starting_balance": "33.00",
            "ending_balance": "22.00",
            "amount": "11.00",
            "action": "applied_to_invoice",
            "description": "An optional description",
            "invoice": {
              "id": "gXcsPTVyC4YZa3Sc"
            },
            "type": "increment",
            "credit_note": {
              "id": "<string>"
            }
          }
        ],
        "status": "issued",
        "invoice_source": "subscription",
        "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>"
        },
        "hosted_invoice_url": "<string>",
        "will_auto_issue": true,
        "eligible_to_issue_at": "2023-11-07T05:31:56Z",
        "customer_tax_id": {
          "country": "AD",
          "type": "ad_nrt",
          "value": "<string>"
        },
        "memo": "<string>",
        "credit_notes": [
          {
            "id": "<string>",
            "credit_note_number": "<string>",
            "reason": "<string>",
            "total": "<string>",
            "voided_at": "2022-05-01T07:01:31+00:00",
            "type": "<string>",
            "memo": "<string>"
          }
        ],
        "payment_attempts": [
          {
            "id": "<string>",
            "payment_provider": "stripe",
            "payment_provider_id": "<string>",
            "amount": "<string>",
            "succeeded": true,
            "created_at": "2023-11-07T05:31:56Z"
          }
        ],
        "invoice_date": "2022-05-01T07:00:00+00:00"
      }
    ],
    "voided_invoices": [
      {
        "metadata": {},
        "voided_at": "2023-11-07T05:31:56Z",
        "paid_at": "2023-11-07T05:31:56Z",
        "issued_at": "2023-11-07T05:31:56Z",
        "scheduled_issue_at": "2023-11-07T05:31:56Z",
        "auto_collection": {
          "next_attempt_at": "2023-11-07T05:31:56Z",
          "previously_attempted_at": "2023-11-07T05:31:56Z",
          "enabled": true,
          "num_attempts": 123
        },
        "issue_failed_at": "2023-11-07T05:31:56Z",
        "sync_failed_at": "2023-11-07T05:31:56Z",
        "payment_failed_at": "2023-11-07T05:31:56Z",
        "payment_started_at": "2023-11-07T05:31:56Z",
        "amount_due": "8.00",
        "created_at": "2022-05-01T07:01:31+00:00",
        "currency": "USD",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "discount": "<any>",
        "discounts": [
          {
            "discount_type": "percentage",
            "applies_to_price_ids": [
              "h74gfhdjvn7ujokd",
              "7hfgtgjnbvc3ujkl"
            ],
            "reason": "<string>",
            "percentage_discount": 0.15
          }
        ],
        "due_date": "2022-05-30T07:00:00+00:00",
        "id": "<string>",
        "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
        "invoice_number": "JYEFHK-00001",
        "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>",
        "line_items": [
          {
            "amount": "7.00",
            "discount": {
              "discount_type": "percentage",
              "applies_to_price_ids": [
                "h74gfhdjvn7ujokd",
                "7hfgtgjnbvc3ujkl"
              ],
              "reason": "<string>",
              "percentage_discount": 0.15
            },
            "end_date": "2022-02-01T08:00:00+00:00",
            "grouping": "<string>",
            "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>",
            "adjustments": [
              {
                "id": "<string>",
                "is_invoice_level": true,
                "filters": [
                  {
                    "field": "price_id",
                    "operator": "includes",
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "reason": "<string>",
                "adjustment_type": "usage_discount",
                "usage_discount": 123,
                "amount": "<string>"
              }
            ],
            "name": "Fixed Fee",
            "quantity": 1,
            "start_date": "2022-02-01T08:00:00+00:00",
            "subtotal": "9.00",
            "adjusted_subtotal": "5.00",
            "credits_applied": "6.00",
            "partially_invoiced_amount": "4.00",
            "sub_line_items": [
              {
                "amount": "9.00",
                "name": "Tier One",
                "quantity": 5,
                "grouping": {
                  "key": "region",
                  "value": "west"
                },
                "type": "matrix",
                "matrix_config": {
                  "dimension_values": [
                    "<string>"
                  ]
                }
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "id": "<string>",
            "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>"
              }
            },
            "usage_customer_ids": [
              "<string>"
            ],
            "filter": "<string>"
          }
        ],
        "subscription": {
          "id": "VDGsT23osdLb84KD"
        },
        "subtotal": "8.00",
        "total": "8.00",
        "customer_balance_transactions": [
          {
            "id": "cgZa3SXcsPTVyC4Y",
            "created_at": "2022-05-01T07:01:31+00:00",
            "starting_balance": "33.00",
            "ending_balance": "22.00",
            "amount": "11.00",
            "action": "applied_to_invoice",
            "description": "An optional description",
            "invoice": {
              "id": "gXcsPTVyC4YZa3Sc"
            },
            "type": "increment",
            "credit_note": {
              "id": "<string>"
            }
          }
        ],
        "status": "issued",
        "invoice_source": "subscription",
        "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>"
        },
        "hosted_invoice_url": "<string>",
        "will_auto_issue": true,
        "eligible_to_issue_at": "2023-11-07T05:31:56Z",
        "customer_tax_id": {
          "country": "AD",
          "type": "ad_nrt",
          "value": "<string>"
        },
        "memo": "<string>",
        "credit_notes": [
          {
            "id": "<string>",
            "credit_note_number": "<string>",
            "reason": "<string>",
            "total": "<string>",
            "voided_at": "2022-05-01T07:01:31+00:00",
            "type": "<string>",
            "memo": "<string>"
          }
        ],
        "payment_attempts": [
          {
            "id": "<string>",
            "payment_provider": "stripe",
            "payment_provider_id": "<string>",
            "amount": "<string>",
            "succeeded": true,
            "created_at": "2023-11-07T05:31:56Z"
          }
        ],
        "invoice_date": "2022-05-01T07:00:00+00:00"
      }
    ]
  }
}

API documentation

Alert

Coupon

Credit note

Customer

Credit

Dimensional Price Group

Event

Invoice

Item

Metric

Availability

Plan

Price

Subscription Change

Subscription

Price interval

Create subscription

Customize your customer’s subscriptions

Adding Prices

Removing Prices

Replacing Prices

Adding adjustments

Removing adjustments

Replacing adjustments

Price overrides (DEPRECATED)

Maximums and Minimums

Minimum override example

Discounts

Threshold Billing

Authorizations

Body

Response