Skip to main content
POST
/
subscriptions
Create subscription
curl --request POST \
  --url https://api.withorb.com/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "usage_customer_ids": [
    "<string>"
  ],
  "filter": "my_property > 100 AND my_other_property = 'bar'",
  "metadata": {},
  "plan_id": "ZMwNQefe7J3ecf7W",
  "external_plan_id": "ZMwNQefe7J3ecf7W",
  "price_overrides": [
    "<unknown>"
  ],
  "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": {
        "model_type": "unit",
        "unit_config": {
          "unit_amount": "<string>",
          "prorated": false
        },
        "name": "<string>",
        "item_id": "<string>",
        "cadence": "annual",
        "metadata": {},
        "external_price_id": "<string>",
        "dimensional_price_configuration": {
          "dimension_values": [
            "<string>"
          ],
          "dimensional_price_group_id": "<string>",
          "external_dimensional_price_group_id": "<string>"
        },
        "billable_metric_id": "<string>",
        "billed_in_advance": true,
        "fixed_price_quantity": 123,
        "invoice_grouping_key": "<string>",
        "billing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "invoicing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "conversion_rate": 123,
        "conversion_rate_config": {
          "conversion_rate_type": "unit",
          "unit_config": {
            "unit_amount": "<string>"
          }
        },
        "currency": "<string>",
        "reference_id": "<string>"
      },
      "allocation_price": {
        "currency": "<string>",
        "amount": "<string>",
        "cadence": "one_time",
        "expires_at_end_of_cadence": true,
        "custom_expiration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "filters": [
          {
            "field": "item_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "per_unit_cost_basis": "0.00",
        "item_id": "<string>"
      },
      "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": [
    {
      "replaces_price_id": "<string>",
      "price_id": "h74gfhdjvn7ujokd",
      "external_price_id": "external_price_id",
      "price": {
        "model_type": "unit",
        "unit_config": {
          "unit_amount": "<string>",
          "prorated": false
        },
        "name": "<string>",
        "item_id": "<string>",
        "cadence": "annual",
        "metadata": {},
        "external_price_id": "<string>",
        "dimensional_price_configuration": {
          "dimension_values": [
            "<string>"
          ],
          "dimensional_price_group_id": "<string>",
          "external_dimensional_price_group_id": "<string>"
        },
        "billable_metric_id": "<string>",
        "billed_in_advance": true,
        "fixed_price_quantity": 123,
        "invoice_grouping_key": "<string>",
        "billing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "invoicing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "conversion_rate": 123,
        "conversion_rate_config": {
          "conversion_rate_type": "unit",
          "unit_config": {
            "unit_amount": "<string>"
          }
        },
        "currency": "<string>",
        "reference_id": "<string>"
      },
      "allocation_price": {
        "currency": "<string>",
        "amount": "<string>",
        "cadence": "one_time",
        "expires_at_end_of_cadence": true,
        "custom_expiration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "filters": [
          {
            "field": "item_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "per_unit_cost_basis": "0.00",
        "item_id": "<string>"
      },
      "fixed_price_quantity": 2,
      "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": {
        "adjustment_type": "percentage_discount",
        "percentage_discount": 123,
        "applies_to_price_ids": [
          "price_1",
          "price_2"
        ],
        "applies_to_item_ids": [
          "item_1",
          "item_2"
        ],
        "applies_to_all": true,
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "currency": [
          "USD",
          "JPY",
          "credits"
        ],
        "price_type": "usage",
        "is_invoice_level": true
      },
      "start_date": "2023-05-01",
      "end_date": "2023-07-10",
      "plan_phase_order": 123
    }
  ],
  "remove_adjustments": [
    {
      "adjustment_id": "<string>"
    }
  ],
  "replace_adjustments": [
    {
      "adjustment": {
        "adjustment_type": "percentage_discount",
        "percentage_discount": 123,
        "applies_to_price_ids": [
          "price_1",
          "price_2"
        ],
        "applies_to_item_ids": [
          "item_1",
          "item_2"
        ],
        "applies_to_all": true,
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "currency": [
          "USD",
          "JPY",
          "credits"
        ],
        "price_type": "usage",
        "is_invoice_level": true
      },
      "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
  }
}
EOF
{
  "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,
    "auto_issuance": true,
    "additional_emails": [
      "<string>"
    ],
    "portal_url": "<string>",
    "hierarchy": {
      "parent": {
        "id": "<string>",
        "external_customer_id": "<string>"
      },
      "children": [
        {
          "id": "<string>",
          "external_customer_id": "<string>"
        }
      ]
    },
    "accounting_sync_configuration": {
      "excluded": true,
      "accounting_providers": [
        {
          "provider_type": "quickbooks",
          "external_provider_id": "<string>"
        }
      ]
    },
    "reporting_configuration": {
      "exempt": true
    },
    "payment_configuration": {
      "payment_providers": []
    },
    "automatic_tax_enabled": true
  },
  "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",
      "percentage_discount": 0.5,
      "applies_to_price_ids": [
        "h74gfhdjvn7ujokd",
        "7hfgtgjnbvc3ujkl"
      ],
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<string>"
          ]
        }
      ],
      "reason": "<string>"
    },
    "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",
          "percentage_discount": 0.5,
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<string>"
        }
      }
    ],
    "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": [
      {
        "model_type": "unit",
        "unit_config": {
          "unit_amount": "<string>",
          "prorated": false
        },
        "metadata": {},
        "id": "<string>",
        "name": "<string>",
        "external_price_id": "<string>",
        "replaces_price_id": "<string>",
        "price_type": "usage_price",
        "created_at": "2023-11-07T05:31:56Z",
        "cadence": "one_time",
        "billing_mode": "in_advance",
        "billing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "invoicing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "billable_metric": {
          "id": "<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"
          },
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ]
        },
        "composite_price_filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "discount": {
          "discount_type": "percentage",
          "percentage_discount": 0.5,
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<string>"
        },
        "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>",
        "dimensional_price_configuration": {
          "dimensional_price_group_id": "<string>",
          "dimension_values": [
            "<string>"
          ]
        }
      }
    ],
    "adjustments": [
      {
        "id": "<string>",
        "is_invoice_level": true,
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ],
        "reason": "<string>",
        "replaces_adjustment_id": "<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": {
        "model_type": "unit",
        "unit_config": {
          "unit_amount": "<string>",
          "prorated": false
        },
        "metadata": {},
        "id": "<string>",
        "name": "<string>",
        "external_price_id": "<string>",
        "replaces_price_id": "<string>",
        "price_type": "usage_price",
        "created_at": "2023-11-07T05:31:56Z",
        "cadence": "one_time",
        "billing_mode": "in_advance",
        "billing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "invoicing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "billable_metric": {
          "id": "<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"
          },
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ]
        },
        "composite_price_filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "discount": {
          "discount_type": "percentage",
          "percentage_discount": 0.5,
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<string>"
        },
        "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>",
        "dimensional_price_configuration": {
          "dimensional_price_group_id": "<string>",
          "dimension_values": [
            "<string>"
          ]
        }
      },
      "billing_cycle_day": 123,
      "can_defer_billing": true,
      "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>",
        "replaces_adjustment_id": "<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>",
        "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,
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "item_id": "<string>",
            "discounts": [],
            "start_time_inclusive": "2023-11-07T05:31:56Z",
            "end_time_exclusive": "2023-11-07T05:31:56Z"
          }
        ],
        "discounts": []
      }
    ],
    "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>",
        "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,
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "item_id": "<string>",
            "discounts": [],
            "start_time_inclusive": "2023-11-07T05:31:56Z",
            "end_time_exclusive": "2023-11-07T05:31:56Z"
          }
        ],
        "discounts": []
      }
    ],
    "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": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "currency": "<string>",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "due_date": "2022-05-30T07:00:00+00:00",
        "id": "<string>",
        "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
        "invoice_number": "<string>",
        "subscription": {
          "id": "<string>"
        },
        "total": "<string>",
        "customer_balance_transactions": [
          {
            "id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "starting_balance": "<string>",
            "ending_balance": "<string>",
            "amount": "<string>",
            "action": "applied_to_invoice",
            "description": "An optional description",
            "invoice": {
              "id": "<string>"
            },
            "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",
            "receipt_pdf": "https://assets.withorb.com/receipt/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"
          }
        ],
        "discount": "<unknown>",
        "discounts": [
          {
            "discount_type": "percentage",
            "percentage_discount": 0.5,
            "applies_to_price_ids": [
              "h74gfhdjvn7ujokd",
              "7hfgtgjnbvc3ujkl"
            ],
            "filters": [
              {
                "field": "price_id",
                "operator": "includes",
                "values": [
                  "<string>"
                ]
              }
            ],
            "reason": "<string>"
          }
        ],
        "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>",
        "line_items": [
          {
            "amount": "<string>",
            "end_date": "2023-11-07T05:31:56Z",
            "grouping": "<string>",
            "adjustments": [
              {
                "id": "<string>",
                "is_invoice_level": true,
                "filters": [
                  {
                    "field": "price_id",
                    "operator": "includes",
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "applies_to_price_ids": [
                  "<string>"
                ],
                "reason": "<string>",
                "replaces_adjustment_id": "<string>",
                "adjustment_type": "usage_discount",
                "usage_discount": 123,
                "amount": "<string>"
              }
            ],
            "name": "<string>",
            "quantity": 123,
            "start_date": "2023-11-07T05:31:56Z",
            "subtotal": "<string>",
            "adjusted_subtotal": "<string>",
            "credits_applied": "<string>",
            "partially_invoiced_amount": "<string>",
            "sub_line_items": [
              {
                "amount": "<string>",
                "name": "<string>",
                "quantity": 123,
                "grouping": {
                  "key": "<string>",
                  "value": "west"
                },
                "type": "matrix",
                "matrix_config": {
                  "dimension_values": [
                    "<string>"
                  ]
                },
                "scaled_quantity": 123
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "id": "<string>",
            "price": {
              "model_type": "unit",
              "unit_config": {
                "unit_amount": "<string>",
                "prorated": false
              },
              "metadata": {},
              "id": "<string>",
              "name": "<string>",
              "external_price_id": "<string>",
              "replaces_price_id": "<string>",
              "price_type": "usage_price",
              "created_at": "2023-11-07T05:31:56Z",
              "cadence": "one_time",
              "billing_mode": "in_advance",
              "billing_cycle_configuration": {
                "duration": 123,
                "duration_unit": "day"
              },
              "invoicing_cycle_configuration": {
                "duration": 123,
                "duration_unit": "day"
              },
              "billable_metric": {
                "id": "<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"
                },
                "filters": [
                  {
                    "field": "price_id",
                    "operator": "includes",
                    "values": [
                      "<string>"
                    ]
                  }
                ]
              },
              "composite_price_filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "discount": {
                "discount_type": "percentage",
                "percentage_discount": 0.5,
                "applies_to_price_ids": [
                  "h74gfhdjvn7ujokd",
                  "7hfgtgjnbvc3ujkl"
                ],
                "filters": [
                  {
                    "field": "price_id",
                    "operator": "includes",
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "reason": "<string>"
              },
              "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>",
              "dimensional_price_configuration": {
                "dimensional_price_group_id": "<string>",
                "dimension_values": [
                  "<string>"
                ]
              }
            },
            "usage_customer_ids": [
              "<string>"
            ],
            "filter": "<string>"
          }
        ],
        "subtotal": "<string>",
        "invoice_date": "2023-11-07T05:31:56Z",
        "is_payable_now": true
      }
    ],
    "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": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "currency": "<string>",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "due_date": "2022-05-30T07:00:00+00:00",
        "id": "<string>",
        "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
        "invoice_number": "<string>",
        "subscription": {
          "id": "<string>"
        },
        "total": "<string>",
        "customer_balance_transactions": [
          {
            "id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "starting_balance": "<string>",
            "ending_balance": "<string>",
            "amount": "<string>",
            "action": "applied_to_invoice",
            "description": "An optional description",
            "invoice": {
              "id": "<string>"
            },
            "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",
            "receipt_pdf": "https://assets.withorb.com/receipt/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"
          }
        ],
        "discount": "<unknown>",
        "discounts": [
          {
            "discount_type": "percentage",
            "percentage_discount": 0.5,
            "applies_to_price_ids": [
              "h74gfhdjvn7ujokd",
              "7hfgtgjnbvc3ujkl"
            ],
            "filters": [
              {
                "field": "price_id",
                "operator": "includes",
                "values": [
                  "<string>"
                ]
              }
            ],
            "reason": "<string>"
          }
        ],
        "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>",
        "line_items": [
          {
            "amount": "<string>",
            "end_date": "2023-11-07T05:31:56Z",
            "grouping": "<string>",
            "adjustments": [
              {
                "id": "<string>",
                "is_invoice_level": true,
                "filters": [
                  {
                    "field": "price_id",
                    "operator": "includes",
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "applies_to_price_ids": [
                  "<string>"
                ],
                "reason": "<string>",
                "replaces_adjustment_id": "<string>",
                "adjustment_type": "usage_discount",
                "usage_discount": 123,
                "amount": "<string>"
              }
            ],
            "name": "<string>",
            "quantity": 123,
            "start_date": "2023-11-07T05:31:56Z",
            "subtotal": "<string>",
            "adjusted_subtotal": "<string>",
            "credits_applied": "<string>",
            "partially_invoiced_amount": "<string>",
            "sub_line_items": [
              {
                "amount": "<string>",
                "name": "<string>",
                "quantity": 123,
                "grouping": {
                  "key": "<string>",
                  "value": "west"
                },
                "type": "matrix",
                "matrix_config": {
                  "dimension_values": [
                    "<string>"
                  ]
                },
                "scaled_quantity": 123
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "id": "<string>",
            "price": {
              "model_type": "unit",
              "unit_config": {
                "unit_amount": "<string>",
                "prorated": false
              },
              "metadata": {},
              "id": "<string>",
              "name": "<string>",
              "external_price_id": "<string>",
              "replaces_price_id": "<string>",
              "price_type": "usage_price",
              "created_at": "2023-11-07T05:31:56Z",
              "cadence": "one_time",
              "billing_mode": "in_advance",
              "billing_cycle_configuration": {
                "duration": 123,
                "duration_unit": "day"
              },
              "invoicing_cycle_configuration": {
                "duration": 123,
                "duration_unit": "day"
              },
              "billable_metric": {
                "id": "<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"
                },
                "filters": [
                  {
                    "field": "price_id",
                    "operator": "includes",
                    "values": [
                      "<string>"
                    ]
                  }
                ]
              },
              "composite_price_filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "discount": {
                "discount_type": "percentage",
                "percentage_discount": 0.5,
                "applies_to_price_ids": [
                  "h74gfhdjvn7ujokd",
                  "7hfgtgjnbvc3ujkl"
                ],
                "filters": [
                  {
                    "field": "price_id",
                    "operator": "includes",
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "reason": "<string>"
              },
              "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>",
              "dimensional_price_configuration": {
                "dimensional_price_group_id": "<string>",
                "dimension_values": [
                  "<string>"
                ]
              }
            },
            "usage_customer_ids": [
              "<string>"
            ],
            "filter": "<string>"
          }
        ],
        "subtotal": "<string>",
        "invoice_date": "2023-11-07T05:31:56Z"
      }
    ]
  }
}

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.

Example:

"my_property > 100 AND my_other_property = 'bar'"

​
metadata
Metadata · object

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.

Example:

"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.

Example:

"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.

Example:

"10.00"

​
initial_phase_order
integer | null

The phase of the plan to start with

Example:

2

​
add_prices
AddSubscriptionPriceParams · object[] | null

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

​
remove_prices
RemoveSubscriptionPriceParams · object[] | null

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

​
replace_prices
ReplaceSubscriptionPriceParams · 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
AddSubscriptionAdjustmentParams · object[] | null

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

​
remove_adjustments
RemoveSubscriptionAdjustmentParams · object[] | null

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

​
replace_adjustments
ReplaceSubscriptionAdjustmentParams · 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<date-time> | null
​
end_date
string<date-time> | 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
BillingCycleAnchorConfiguration · object

Response

Created

​
metadata
Metadata · object
required

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

​
id
string
required
​
customer
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
Plan · object
required

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

​
name
string
required

The name of the subscription.

​
start_date
string<date-time>
required

The date Orb starts billing for this subscription.

​
end_date
string<date-time> | null
required

The date Orb stops billing for this subscription.

​
created_at
string<date-time>
required
​
current_billing_period_start_date
string<date-time> | 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<date-time> | 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
SubscriptionTrialInfo · 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
FixedFeeQuantityScheduleEntry · 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
CouponRedemption · object
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
BillingCycleAnchorConfiguration · object
required
​
invoicing_threshold
string | null
required
​
price_intervals
PriceInterval · object[]
required

The price intervals for this subscription.

​
adjustment_intervals
AdjustmentInterval · object[]
required

The adjustment intervals for this subscription sorted by the start_date of the adjustment interval.

​
discount_intervals
(AmountDiscountInterval · object | PercentageDiscountInterval · object | UsageDiscountInterval · object)[]
required
deprecated

The discount intervals for this subscription sorted by the start_date. This field is deprecated in favor of adjustment_intervals.

​
minimum_intervals
MinimumInterval · object[]
required
deprecated

The minimum intervals for this subscription sorted by the start_date. This field is deprecated in favor of adjustment_intervals.

​
maximum_intervals
MaximumInterval · object[]
required
deprecated

The maximum intervals for this subscription sorted by the start_date. This field is deprecated in favor of adjustment_intervals.

​
pending_subscription_change
SubscriptionChangeMinified · object
required

A pending subscription change if one exists on this subscription.

​
changed_resources
ChangedSubscriptionResources · object

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.