Update trial for subscription

This endpoint is used to update the trial end date for a subscription. The new trial end date must be within the time range of the current plan (i.e. the new trial end date must be on or after the subscription’s start date on the current plan, and on or before the subscription end date).

In order to retroactively remove a trial completely, the end date can be set to the transition date of the subscription to this plan (or, if this is the first plan for this subscription, the subscription’s start date). In order to end a trial immediately, the keyword immediate can be provided as the trial end date.

By default, Orb will shift only the trial end date (and price intervals that start or end on the previous trial end date), and leave all other future price intervals untouched. If the shift parameter is set to true, Orb will shift all subsequent price and adjustment intervals by the same amount as the trial end date shift (so, e.g., if a plan change is scheduled or an add-on price was added, that change will be pushed back by the same amount of time the trial is extended).

POST /subscriptions/{subscription_id}/update_trial

Update trial for subscription

cURL

curl --request POST \
  --url https://api.withorb.com/v1/subscriptions/{subscription_id}/update_trial \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "trial_end_date": "2017-07-21T17:32:28Z",
  "shift": false
}
'

200

{
  "metadata": {},
  "id": "<string>",
  "customer": {
    "metadata": {},
    "id": "<string>",
    "external_customer_id": "<string>",
    "name": "<string>",
    "email": "<string>",
    "timezone": "<string>",
    "payment_provider_id": "<string>",
    "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": {
      "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": [
        {
          "external_provider_id": "<string>"
        }
      ]
    },
    "reporting_configuration": {
      "exempt": true
    },
    "payment_configuration": {
      "payment_providers": []
    },
    "default_payment_method": {
      "id": "<string>",
      "provider_type": "<string>",
      "external_payment_method_id": "<string>",
      "customer_id": "<string>",
      "default": true,
      "created_at": "2023-11-07T05:31:56Z"
    },
    "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",
    "maximum": {
      "maximum_amount": "<string>",
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "minimum": {
      "minimum_amount": "<string>",
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "discount": {
      "percentage_discount": 0.5,
      "applies_to_price_ids": [
        "h74gfhdjvn7ujokd",
        "7hfgtgjnbvc3ujkl"
      ],
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "reason": "<string>"
    },
    "product": {
      "created_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "name": "<string>"
    },
    "version": 123,
    "trial_config": {
      "trial_period": 123
    },
    "plan_phases": [
      {
        "id": "<string>",
        "description": "<string>",
        "duration": 123,
        "name": "<string>",
        "order": 123,
        "minimum": {
          "minimum_amount": "<string>",
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum": {
          "maximum_amount": "<string>",
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum_amount": "<string>",
        "minimum_amount": "<string>",
        "discount": {
          "percentage_discount": 0.5,
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "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": [
      {
        "unit_config": {
          "unit_amount": "<string>",
          "prorated": false
        },
        "metadata": {},
        "id": "<string>",
        "name": "<string>",
        "external_price_id": "<string>",
        "replaces_price_id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "billing_cycle_configuration": {
          "duration": 123
        },
        "invoicing_cycle_configuration": {
          "duration": 123
        },
        "billable_metric": {
          "id": "<string>"
        },
        "fixed_price_quantity": 123,
        "plan_phase_order": 123,
        "currency": "<string>",
        "conversion_rate": 123,
        "conversion_rate_config": {
          "unit_config": {
            "unit_amount": "<string>"
          }
        },
        "item": {
          "id": "<string>",
          "name": "<string>"
        },
        "credit_allocation": {
          "currency": "<string>",
          "allows_rollover": true,
          "custom_expiration": {
            "duration": 123
          },
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "license_type_id": "<string>"
        },
        "composite_price_filters": [
          {
            "values": [
              "<string>"
            ]
          }
        ],
        "invoice_grouping_key": "<string>",
        "discount": {
          "percentage_discount": 0.5,
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<string>"
        },
        "minimum": {
          "minimum_amount": "<string>",
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "minimum_amount": "<string>",
        "maximum": {
          "maximum_amount": "<string>",
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum_amount": "<string>",
        "dimensional_price_configuration": {
          "dimensional_price_group_id": "<string>",
          "dimension_values": [
            "<string>"
          ]
        },
        "license_type": {
          "id": "<string>",
          "name": "<string>",
          "grouping_key": "<string>"
        }
      }
    ],
    "adjustments": [
      {
        "id": "<string>",
        "is_invoice_level": true,
        "filters": [
          {
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ],
        "reason": "<string>",
        "replaces_adjustment_id": "<string>",
        "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",
  "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": {
        "unit_config": {
          "unit_amount": "<string>",
          "prorated": false
        },
        "metadata": {},
        "id": "<string>",
        "name": "<string>",
        "external_price_id": "<string>",
        "replaces_price_id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "billing_cycle_configuration": {
          "duration": 123
        },
        "invoicing_cycle_configuration": {
          "duration": 123
        },
        "billable_metric": {
          "id": "<string>"
        },
        "fixed_price_quantity": 123,
        "plan_phase_order": 123,
        "currency": "<string>",
        "conversion_rate": 123,
        "conversion_rate_config": {
          "unit_config": {
            "unit_amount": "<string>"
          }
        },
        "item": {
          "id": "<string>",
          "name": "<string>"
        },
        "credit_allocation": {
          "currency": "<string>",
          "allows_rollover": true,
          "custom_expiration": {
            "duration": 123
          },
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "license_type_id": "<string>"
        },
        "composite_price_filters": [
          {
            "values": [
              "<string>"
            ]
          }
        ],
        "invoice_grouping_key": "<string>",
        "discount": {
          "percentage_discount": 0.5,
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<string>"
        },
        "minimum": {
          "minimum_amount": "<string>",
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "minimum_amount": "<string>",
        "maximum": {
          "maximum_amount": "<string>",
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum_amount": "<string>",
        "dimensional_price_configuration": {
          "dimensional_price_group_id": "<string>",
          "dimension_values": [
            "<string>"
          ]
        },
        "license_type": {
          "id": "<string>",
          "name": "<string>",
          "grouping_key": "<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>"
      ],
      "metric_parameter_overrides": {}
    }
  ],
  "adjustment_intervals": [
    {
      "id": "<string>",
      "adjustment": {
        "id": "<string>",
        "is_invoice_level": true,
        "filters": [
          {
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ],
        "reason": "<string>",
        "replaces_adjustment_id": "<string>",
        "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": [
    {
      "amount_discount": "<string>",
      "start_date": "2023-11-07T05:31:56Z",
      "end_date": "2023-11-07T05:31:56Z",
      "filters": [
        {
          "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": [
        {
          "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": [
        {
          "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>",
        "subtotal": "<string>",
        "total": "<string>",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "credit_note_pdf": "<string>",
        "minimum_amount_refunded": "<string>",
        "maximum_amount_adjustment": {
          "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>",
        "subtotal": "<string>",
        "total": "<string>",
        "customer": {
          "id": "<string>",
          "external_customer_id": "<string>"
        },
        "credit_note_pdf": "<string>",
        "minimum_amount_refunded": "<string>",
        "maximum_amount_adjustment": {
          "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>",
            "description": "An optional description",
            "invoice": {
              "id": "<string>"
            },
            "credit_note": {
              "id": "<string>"
            }
          }
        ],
        "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": {
          "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_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": [
          {
            "percentage_discount": 0.5,
            "applies_to_price_ids": [
              "h74gfhdjvn7ujokd",
              "7hfgtgjnbvc3ujkl"
            ],
            "filters": [
              {
                "values": [
                  "<string>"
                ]
              }
            ],
            "reason": "<string>"
          }
        ],
        "minimum": {
          "minimum_amount": "<string>",
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "minimum_amount": "<string>",
        "maximum": {
          "maximum_amount": "<string>",
          "filters": [
            {
              "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": [
                  {
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "applies_to_price_ids": [
                  "<string>"
                ],
                "reason": "<string>",
                "replaces_adjustment_id": "<string>",
                "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"
                },
                "matrix_config": {
                  "dimension_values": [
                    "<string>"
                  ]
                },
                "scaled_quantity": 123
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "id": "<string>",
            "price": {
              "unit_config": {
                "unit_amount": "<string>",
                "prorated": false
              },
              "metadata": {},
              "id": "<string>",
              "name": "<string>",
              "external_price_id": "<string>",
              "replaces_price_id": "<string>",
              "created_at": "2023-11-07T05:31:56Z",
              "billing_cycle_configuration": {
                "duration": 123
              },
              "invoicing_cycle_configuration": {
                "duration": 123
              },
              "billable_metric": {
                "id": "<string>"
              },
              "fixed_price_quantity": 123,
              "plan_phase_order": 123,
              "currency": "<string>",
              "conversion_rate": 123,
              "conversion_rate_config": {
                "unit_config": {
                  "unit_amount": "<string>"
                }
              },
              "item": {
                "id": "<string>",
                "name": "<string>"
              },
              "credit_allocation": {
                "currency": "<string>",
                "allows_rollover": true,
                "custom_expiration": {
                  "duration": 123
                },
                "filters": [
                  {
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "license_type_id": "<string>"
              },
              "composite_price_filters": [
                {
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "invoice_grouping_key": "<string>",
              "discount": {
                "percentage_discount": 0.5,
                "applies_to_price_ids": [
                  "h74gfhdjvn7ujokd",
                  "7hfgtgjnbvc3ujkl"
                ],
                "filters": [
                  {
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "reason": "<string>"
              },
              "minimum": {
                "minimum_amount": "<string>",
                "filters": [
                  {
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "applies_to_price_ids": [
                  "<string>"
                ]
              },
              "minimum_amount": "<string>",
              "maximum": {
                "maximum_amount": "<string>",
                "filters": [
                  {
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "applies_to_price_ids": [
                  "<string>"
                ]
              },
              "maximum_amount": "<string>",
              "dimensional_price_configuration": {
                "dimensional_price_group_id": "<string>",
                "dimension_values": [
                  "<string>"
                ]
              },
              "license_type": {
                "id": "<string>",
                "name": "<string>",
                "grouping_key": "<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>",
            "description": "An optional description",
            "invoice": {
              "id": "<string>"
            },
            "credit_note": {
              "id": "<string>"
            }
          }
        ],
        "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": {
          "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_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": [
          {
            "percentage_discount": 0.5,
            "applies_to_price_ids": [
              "h74gfhdjvn7ujokd",
              "7hfgtgjnbvc3ujkl"
            ],
            "filters": [
              {
                "values": [
                  "<string>"
                ]
              }
            ],
            "reason": "<string>"
          }
        ],
        "minimum": {
          "minimum_amount": "<string>",
          "filters": [
            {
              "values": [
                "<string>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "minimum_amount": "<string>",
        "maximum": {
          "maximum_amount": "<string>",
          "filters": [
            {
              "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": [
                  {
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "applies_to_price_ids": [
                  "<string>"
                ],
                "reason": "<string>",
                "replaces_adjustment_id": "<string>",
                "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"
                },
                "matrix_config": {
                  "dimension_values": [
                    "<string>"
                  ]
                },
                "scaled_quantity": 123
              }
            ],
            "tax_amounts": [
              {
                "tax_rate_description": "<string>",
                "tax_rate_percentage": "<string>",
                "amount": "<string>"
              }
            ],
            "id": "<string>",
            "price": {
              "unit_config": {
                "unit_amount": "<string>",
                "prorated": false
              },
              "metadata": {},
              "id": "<string>",
              "name": "<string>",
              "external_price_id": "<string>",
              "replaces_price_id": "<string>",
              "created_at": "2023-11-07T05:31:56Z",
              "billing_cycle_configuration": {
                "duration": 123
              },
              "invoicing_cycle_configuration": {
                "duration": 123
              },
              "billable_metric": {
                "id": "<string>"
              },
              "fixed_price_quantity": 123,
              "plan_phase_order": 123,
              "currency": "<string>",
              "conversion_rate": 123,
              "conversion_rate_config": {
                "unit_config": {
                  "unit_amount": "<string>"
                }
              },
              "item": {
                "id": "<string>",
                "name": "<string>"
              },
              "credit_allocation": {
                "currency": "<string>",
                "allows_rollover": true,
                "custom_expiration": {
                  "duration": 123
                },
                "filters": [
                  {
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "license_type_id": "<string>"
              },
              "composite_price_filters": [
                {
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "invoice_grouping_key": "<string>",
              "discount": {
                "percentage_discount": 0.5,
                "applies_to_price_ids": [
                  "h74gfhdjvn7ujokd",
                  "7hfgtgjnbvc3ujkl"
                ],
                "filters": [
                  {
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "reason": "<string>"
              },
              "minimum": {
                "minimum_amount": "<string>",
                "filters": [
                  {
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "applies_to_price_ids": [
                  "<string>"
                ]
              },
              "minimum_amount": "<string>",
              "maximum": {
                "maximum_amount": "<string>",
                "filters": [
                  {
                    "values": [
                      "<string>"
                    ]
                  }
                ],
                "applies_to_price_ids": [
                  "<string>"
                ]
              },
              "maximum_amount": "<string>",
              "dimensional_price_configuration": {
                "dimensional_price_group_id": "<string>",
                "dimension_values": [
                  "<string>"
                ]
              },
              "license_type": {
                "id": "<string>",
                "name": "<string>",
                "grouping_key": "<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.

Path Parameters

subscription_id · string · required

Body

application/json

trial_end_date · string<date-time> enum<string> · required

The new date that the trial should end, or the literal string immediate to end the trial immediately.

Example:

"2017-07-21T17:32:28Z"

shift · boolean · default: false

If true, shifts subsequent price and adjustment intervals (preserving their durations, but adjusting their absolute dates).

Response

200

application/json

OK

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.

Show child attributes

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.

Show child attributes

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.

Show child attributes

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

Show child attributes

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

Show child attributes

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

Show child attributes

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

Show child attributes

invoicing_threshold · string | null · required

price_intervals · PriceInterval · object[] · required

The price intervals for this subscription.

Show child attributes

adjustment_intervals · AdjustmentInterval · object[] · required

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

Show child attributes

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.

AmountDiscountInterval

PercentageDiscountInterval

UsageDiscountInterval

Show child attributes

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.

Show child attributes

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.

Show child attributes

pending_subscription_change · SubscriptionChangeMinified · object · required

A pending subscription change if one exists on this subscription.

Show child attributes

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.

Show child attributes