PUT
/
subscriptions
/
{subscription_id}
curl --request PUT \
  --url https://api.withorb.com/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {},
  "default_invoice_memo": "<string>",
  "auto_collection": true,
  "net_terms": 123,
  "invoicing_threshold": "10.00"
}'
{
  "metadata": {},
  "id": "<string>",
  "customer": {
    "metadata": {},
    "id": "<string>",
    "external_customer_id": "<string>",
    "name": "<string>",
    "email": "<string>",
    "timezone": "<string>",
    "payment_provider_id": "<string>",
    "payment_provider": "quickbooks",
    "created_at": "2023-11-07T05:31:56Z",
    "shipping_address": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postal_code": "<string>",
      "country": "<string>"
    },
    "billing_address": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postal_code": "<string>",
      "country": "<string>"
    },
    "balance": "<string>",
    "currency": "<string>",
    "tax_id": {
      "country": "AD",
      "type": "ad_nrt",
      "value": "<string>"
    },
    "auto_collection": true,
    "exempt_from_automated_tax": true,
    "email_delivery": true,
    "additional_emails": [
      "<string>"
    ],
    "portal_url": "<string>",
    "accounting_sync_configuration": {
      "excluded": true,
      "accounting_providers": [
        {
          "provider_type": "quickbooks",
          "external_provider_id": "<string>"
        }
      ]
    },
    "reporting_configuration": {
      "exempt": true
    },
    "hierarchy": {
      "parent": {
        "id": "<string>",
        "external_customer_id": "<string>"
      },
      "children": [
        {
          "id": "<string>",
          "external_customer_id": "<string>"
        }
      ]
    }
  },
  "plan": {
    "metadata": {},
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "maximum_amount": "<string>",
    "minimum_amount": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "status": "active",
    "maximum": {
      "maximum_amount": "<string>",
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "minimum": {
      "minimum_amount": "<string>",
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "discount": {
      "discount_type": "percentage",
      "applies_to_price_ids": [
        "h74gfhdjvn7ujokd",
        "7hfgtgjnbvc3ujkl"
      ],
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<string>"
          ]
        }
      ],
      "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>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum": {
          "maximum_amount": "<string>",
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum_amount": "<string>",
        "minimum_amount": "<string>",
        "discount": {
          "discount_type": "percentage",
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "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,
        "conversion_rate_config": {
          "conversion_rate_type": "unit",
          "unit_config": {
            "unit_amount": "<string>"
          }
        },
        "item": {
          "id": "<string>",
          "name": "<string>"
        },
        "credit_allocation": {
          "currency": "<string>",
          "allows_rollover": true,
          "custom_expiration": {
            "duration": 123,
            "duration_unit": "day"
          }
        },
        "discount": {
          "discount_type": "percentage",
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<string>",
          "percentage_discount": 0.15
        },
        "minimum": {
          "minimum_amount": "<string>",
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "minimum_amount": "<string>",
        "maximum": {
          "maximum_amount": "<string>",
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum_amount": "<string>",
        "unit_config": {
          "unit_amount": "<string>"
        }
      }
    ],
    "adjustments": [
      {
        "id": "<string>",
        "is_invoice_level": true,
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<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,
        "conversion_rate_config": {
          "conversion_rate_type": "unit",
          "unit_config": {
            "unit_amount": "<string>"
          }
        },
        "item": {
          "id": "<string>",
          "name": "<string>"
        },
        "credit_allocation": {
          "currency": "<string>",
          "allows_rollover": true,
          "custom_expiration": {
            "duration": 123,
            "duration_unit": "day"
          }
        },
        "discount": {
          "discount_type": "percentage",
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<string>",
          "percentage_discount": 0.15
        },
        "minimum": {
          "minimum_amount": "<string>",
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "minimum_amount": "<string>",
        "maximum": {
          "maximum_amount": "<string>",
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum_amount": "<string>",
        "unit_config": {
          "unit_amount": "<string>"
        }
      },
      "billing_cycle_day": 123,
      "fixed_fee_quantity_transitions": [
        {
          "price_id": "<string>",
          "effective_date": "2023-11-07T05:31:56Z",
          "quantity": 123
        }
      ],
      "current_billing_period_start_date": "2023-11-07T05:31:56Z",
      "current_billing_period_end_date": "2023-11-07T05:31:56Z",
      "filter": "<string>",
      "usage_customer_ids": [
        "<string>"
      ]
    }
  ],
  "adjustment_intervals": [
    {
      "id": "<string>",
      "adjustment": {
        "id": "<string>",
        "is_invoice_level": true,
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ],
        "reason": "<string>",
        "adjustment_type": "usage_discount",
        "usage_discount": 123,
        "plan_phase_order": 123
      },
      "start_date": "2023-11-07T05:31:56Z",
      "end_date": "2023-11-07T05:31:56Z",
      "applies_to_price_interval_ids": [
        "<string>"
      ]
    }
  ],
  "discount_intervals": [
    {
      "discount_type": "amount",
      "amount_discount": "<string>",
      "start_date": "2023-11-07T05:31:56Z",
      "end_date": "2023-11-07T05:31:56Z",
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_interval_ids": [
        "<string>"
      ]
    }
  ],
  "minimum_intervals": [
    {
      "start_date": "2023-11-07T05:31:56Z",
      "end_date": "2023-11-07T05:31:56Z",
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_interval_ids": [
        "<string>"
      ],
      "minimum_amount": "<string>"
    }
  ],
  "maximum_intervals": [
    {
      "start_date": "2023-11-07T05:31:56Z",
      "end_date": "2023-11-07T05:31:56Z",
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_interval_ids": [
        "<string>"
      ],
      "maximum_amount": "<string>"
    }
  ],
  "pending_subscription_change": {
    "id": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
subscription_id
string
required

Body

application/json

Response

200
application/json

OK

A subscription represents the purchase of a plan by a customer.

By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition.

Subscriptions also default to beginning of month alignment, which means the first invoice issued for the subscription will have pro-rated charges between the start_date and the first of the following month. Subsequent billing periods will always start and end on a month boundary (e.g. subsequent month starts for monthly billing).

Depending on the plan configuration, any flat recurring fees will be billed either at the beginning (in-advance) or end (in-arrears) of each billing cycle. Plans default to in-advance billing. Usage-based fees are billed in arrears as usage is accumulated. In the normal course of events, you can expect an invoice to contain usage-based charges for the previous period, and a recurring fee for the following period.