# Create a plan

Creates a plan.

Endpoint: POST /plans
Version: latest
Security: SecretApiKey, JWT

## Request fields

- `type` (string)
  Variant of the plan. This field is optional in create and update requests. The variant is `subscription` when `recurringInterval` is present. If included, this field must match the applicable variant. A mismatch results in an HTTP `422` response. Responses always include this field.
  Enum: "subscription"
- `name` (string, required)
  Name of the plan. This name is displayed on invoices and receipts.
- `description` (string)
  Plain-text description of the plan. This field accepts plain-text only.
- `richDescription` (string)
  Rich-text description of the plan. This field accepts rich text formatting, such as: bold, underline, italic, and hyperlinks.
- `productId` (string, required)
  ID of the related product.
  Example: prod_0YV7DES3WPC5J8JD8QTVNZBZNZ
- `currency` (string, required)
  Currency code in ISO 4217 format.
  Example: USD
- `pricing` (object, required)
  Pricing details.
- `setup` (object | null)
  Setup fee information for the plan.
- `setup.price` (number, required)
  One-time setup fee charged when the plan starts. This field is deprecated. Use the `setupFee` field instead.
- `setupFee` (number | null)
  One-time setup fee charged when the plan starts. Set to `0` or `null` if no setup fee applies.
  Example: 0
- `customFields` (object)
  Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see [Custom fields](https://www.rebilly.com/catalog/all/custom-fields).
  Example: {"foo":"bar"}
- `isActive` (boolean)
  Specifies if the plan is active.
- `recurringInterval` (object, required)
  Service interval settings.
- `recurringInterval.periodAnchorInstruction` (object | null)
  Instruction for calculating the service period anchor. The service period anchor is used, in conjunction with the subscription start time, to calculate when the service period starts and ends.
- `recurringInterval.unit` (string, required)
  Unit of time.
  Enum: "day", "week", "month", "year"
- `recurringInterval.length` (integer, required)
  Length of time.
- `recurringInterval.limit` (integer | null)
  Number of invoices the subscription order generates. If this value is `1`, only the initial order creation is generated. Example: For a 1 year contract that is billed monthly, where the `periodUnit` is `month` and the `periodDuration` is `1`, set this field to `12`.
- `recurringInterval.billingTiming` (string)
  Billing timing in relation to the service period. For `prepaid` plans the customer pays when the service period starts, whereas, for `postpaid` plans, the customer pays when the service period ends.
  Enum: "prepaid", "postpaid"
- `trial` (object | null)
- `trial.price` (number, required)
  Price of setting up a trial. If your service charges a fee for a trial, specify it here. To charge no trial fee, set this value to `0`.
- `trial.period` (object, required)
  Period information.
- `trial.period.unit` (string, required)
  Unit of time.
  Enum: "day", "week", "month", "year"
- `trial.period.length` (integer, required)
  Length of time.
- `meteredBilling` (object | null)
  Use metered billing when an exact quantity is unknown. Report usage during a service period and charge customers afterwards. Metered billing plans must be postpaid.
- `meteredBilling.strategy` (string, required)
  Enum: "sum", "last"
- `meteredBilling.min` (number | null)
  Minimum quantity that is charged at the end of a service period regardless of reported usage.
- `meteredBilling.max` (number | null)
  Maximum quantity that is charged at the end of a service period regardless of reported usage.
- `meteredBilling.sticky` (boolean)
  When enabled, if no usage is reported during a service period, the plan bills the last known reported quantity from a previous period instead of zero. This is suitable for hosted or persistent resources whose usage does not change every period. Only supported with `strategy`: `last`.
  Example: false
- `invoiceTimeShift` (object | null)
  Use invoice time shift to control the billing time. Invoice time shift adjusts the invoice issue and due date when billing must occur before the service period changes. Use invoice time shift in conjunction with `billingTiming` to: - Bill immediately when the service period starts. - Bill immediately after the service period ends. - Bill at an interval of time before the service period starts. - Bill at an interval of time after the service period starts. - Bill at an interval of time before the service period ends. - Bill at an interval of time after the service period ends.
- `invoiceTimeShift.issueTimeShift` (object)
  Calculation instruction of the billing time. This is used in conjunction with the service period anchor to calculate the time at which the invoice is issued. For more information, see [Service period anchor, billing timing, and invoice time shift](https://www.rebilly.com/docs/dev-docs/subscriptions#service-period-anchor-billing-timing-and-invoice-time-shift).
- `invoiceTimeShift.issueTimeShift.chronology` (string, required)
  Sequential order of the billing time relative to the start of the service period.
  Enum: "before"
- `invoiceTimeShift.issueTimeShift.duration` (integer, required)
  Amount of time by which to move the invoice issue time or date.
- `invoiceTimeShift.issueTimeShift.unit` (any, required)
  Unit of time.
- `invoiceTimeShift.dueTimeShift` (object)
  Calculation instruction of the invoice due time. This is used in conjunction with the service period anchor to calculate when an invoice is due for payment. For more information, see [Service period anchor, billing timing, and invoice time shift](https://www.rebilly.com/docs/dev-docs/subscriptions#service-period-anchor-billing-timing-and-invoice-time-shift). The sequential order of due time shift is always after the due date.
- `invoiceTimeShift.dueTimeShift.duration` (integer, required)
  Amount of time by which to move the invoice due time or date.
- `invoiceTimeShift.dueTimeShift.unit` (any, required)
  Unit of time.
- `type` (string)
  Variant of the plan. This field is optional in create and update requests. The variant is `one-time-sale` when both `recurringInterval` and `trial` are omitted. If included, this field must match the applicable variant. A mismatch results in an HTTP `422` response. Responses always include this field.
  Enum: "one-time-sale"
- `type` (string)
  Variant of the plan. This field is optional in create and update requests. The variant is `trial-only` when `trial` is present without `recurringInterval`. If included, this field must match the applicable variant. A mismatch results in an HTTP `422` response. Responses always include this field.
  Enum: "trial-only"
- `trial` (object | null, required)
  Trial configuration settings.

## Response 201 fields

- `id` (string, required)
  ID of the plan.
  Example: plan_0YV7DENSVGDBW9S71XZNNYYQ0X
- `type` (string, required)
  Variant of the plan. This field is optional in create and update requests. The variant is `subscription` when `recurringInterval` is present. If included, this field must match the applicable variant. A mismatch results in an HTTP `422` response. Responses always include this field.
  Enum: "subscription"
- `name` (string, required)
  Name of the plan. This name is displayed on invoices and receipts.
- `description` (string)
  Plain-text description of the plan. This field accepts plain-text only.
- `richDescription` (string)
  Rich-text description of the plan. This field accepts rich text formatting, such as: bold, underline, italic, and hyperlinks.
- `productId` (string, required)
  ID of the related product.
  Example: prod_0YV7DES3WPC5J8JD8QTVNZBZNZ
- `currency` (string, required)
  Currency code in ISO 4217 format.
  Example: USD
- `currencySign` (string)
  Currency sign.
- `pricing` (object, required)
  Pricing details.
- `setup` (object | null)
  Setup fee information for the plan.
- `setup.price` (number, required)
  One-time setup fee charged when the plan starts. This field is deprecated. Use the `setupFee` field instead.
- `setupFee` (number | null)
  One-time setup fee charged when the plan starts. Set to `0` or `null` if no setup fee applies.
  Example: 0
- `customFields` (object)
  Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see [Custom fields](https://www.rebilly.com/catalog/all/custom-fields).
  Example: {"foo":"bar"}
- `isActive` (boolean)
  Specifies if the plan is active.
- `revision` (integer)
  Number of times the plan is modified. Compare this value with materialized subscription item revision values.
- `isTrialOnly` (boolean)
  Specifies if a plan is a trial that does not have recurring instructions.
- `recurringInterval` (null)
  Service interval settings.
- `recurringInterval.periodAnchorInstruction` (object | null)
  Instruction for calculating the service period anchor. The service period anchor is used, in conjunction with the subscription start time, to calculate when the service period starts and ends.
- `recurringInterval.unit` (string, required)
  Unit of time.
  Enum: "day", "week", "month", "year"
- `recurringInterval.length` (integer, required)
  Length of time.
- `recurringInterval.limit` (integer | null)
  Number of invoices the subscription order generates. If this value is `1`, only the initial order creation is generated. Example: For a 1 year contract that is billed monthly, where the `periodUnit` is `month` and the `periodDuration` is `1`, set this field to `12`.
- `recurringInterval.billingTiming` (string)
  Billing timing in relation to the service period. For `prepaid` plans the customer pays when the service period starts, whereas, for `postpaid` plans, the customer pays when the service period ends.
  Enum: "prepaid", "postpaid"
- `trial` (object | null)
- `trial.price` (number, required)
  Price of setting up a trial. If your service charges a fee for a trial, specify it here. To charge no trial fee, set this value to `0`.
- `trial.period` (object, required)
  Period information.
- `trial.period.unit` (string, required)
  Unit of time.
  Enum: "day", "week", "month", "year"
- `trial.period.length` (integer, required)
  Length of time.
- `meteredBilling` (object | null)
  Use metered billing when an exact quantity is unknown. Report usage during a service period and charge customers afterwards. Metered billing plans must be postpaid.
- `meteredBilling.strategy` (string, required)
  Enum: "sum", "last"
- `meteredBilling.min` (number | null)
  Minimum quantity that is charged at the end of a service period regardless of reported usage.
- `meteredBilling.max` (number | null)
  Maximum quantity that is charged at the end of a service period regardless of reported usage.
- `meteredBilling.sticky` (boolean)
  When enabled, if no usage is reported during a service period, the plan bills the last known reported quantity from a previous period instead of zero. This is suitable for hosted or persistent resources whose usage does not change every period. Only supported with `strategy`: `last`.
  Example: false
- `invoiceTimeShift` (object | null)
  Use invoice time shift to control the billing time. Invoice time shift adjusts the invoice issue and due date when billing must occur before the service period changes. Use invoice time shift in conjunction with `billingTiming` to: - Bill immediately when the service period starts. - Bill immediately after the service period ends. - Bill at an interval of time before the service period starts. - Bill at an interval of time after the service period starts. - Bill at an interval of time before the service period ends. - Bill at an interval of time after the service period ends.
- `invoiceTimeShift.issueTimeShift` (object)
  Calculation instruction of the billing time. This is used in conjunction with the service period anchor to calculate the time at which the invoice is issued. For more information, see [Service period anchor, billing timing, and invoice time shift](https://www.rebilly.com/docs/dev-docs/subscriptions#service-period-anchor-billing-timing-and-invoice-time-shift).
- `invoiceTimeShift.issueTimeShift.chronology` (string, required)
  Sequential order of the billing time relative to the start of the service period.
  Enum: "before"
- `invoiceTimeShift.issueTimeShift.duration` (integer, required)
  Amount of time by which to move the invoice issue time or date.
- `invoiceTimeShift.issueTimeShift.unit` (any, required)
  Unit of time.
- `invoiceTimeShift.dueTimeShift` (object)
  Calculation instruction of the invoice due time. This is used in conjunction with the service period anchor to calculate when an invoice is due for payment. For more information, see [Service period anchor, billing timing, and invoice time shift](https://www.rebilly.com/docs/dev-docs/subscriptions#service-period-anchor-billing-timing-and-invoice-time-shift). The sequential order of due time shift is always after the due date.
- `invoiceTimeShift.dueTimeShift.duration` (integer, required)
  Amount of time by which to move the invoice due time or date.
- `invoiceTimeShift.dueTimeShift.unit` (any, required)
  Unit of time.
- `createdTime` (string)
  Date and time when the resource is created. This value is set automatically when the resource is created.
- `updatedTime` (string)
  Date and time when the resource is updated. This value is set automatically when the resource is updated.
- `_links` (array)
  Related links.
- `_links.href` (string)
  Link URL.
- `_links.rel` (string)
  Type of link.
  Enum: "self", "attachments"
- `type` (string, required)
  Variant of the plan. This field is optional in create and update requests. The variant is `one-time-sale` when both `recurringInterval` and `trial` are omitted. If included, this field must match the applicable variant. A mismatch results in an HTTP `422` response. Responses always include this field.
  Enum: "one-time-sale"
- `trial` (null)
  Trial configuration setting.
- `type` (string, required)
  Variant of the plan. This field is optional in create and update requests. The variant is `trial-only` when `trial` is present without `recurringInterval`. If included, this field must match the applicable variant. A mismatch results in an HTTP `422` response. Responses always include this field.
  Enum: "trial-only"
- `trial` (object | null, required)
  Trial configuration settings.

## Response 401 fields

- `status` (integer)
  HTTP status code.
- `type` (string)
  Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
- `title` (string)
  Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
- `detail` (string)
  Human-readable explanation that is specific to this occurrence of the problem.
- `instance` (string)
  URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

## Response 403 fields

- `status` (integer)
  HTTP status code.
- `error` (string)
  Message that describes why the request is forbidden. Most responses use a descriptive message, such as `Not allowed to change security settings`. If the organization requires multi-factor authentication (MFA) and MFA verification has not been completed for the session, this value is `mfa_required`. If the request sets `requireMfa` to `true` and MFA verification has not been completed for the session, this value is `mfa_required_for_caller`. If the organization restricts access to a list of IP addresses and the request comes from an IP address that is not in the list, this value is `ip_not_allowed`.
- `organizationId` (string)
  Unique organization identifier. An organization is an entity that represents a company. For more information, see [Obtain an organization ID](https://www.rebilly.com/docs/settings/organizations-and-websites/#obtain-your-organization-id-and-website-id).
  Example: org_0YVDM8RC7GDADADSBSMW124JA8
- `type` (string)
  Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
- `title` (string)
  Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
- `detail` (string)
  Human-readable explanation that is specific to this occurrence of the problem.
- `instance` (string)
  URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

## Response 422 fields

- `status` (integer)
  HTTP status code.
- `type` (string)
  Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
- `title` (string)
  Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
- `detail` (string)
  Human-readable explanation that is specific to this occurrence of the problem.
- `instance` (string)
  URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
- `invalidFields` (array)
  Invalid field details.
  Example: [{"field":"field1","message":"field1 is invalid"},{"field":"subObject.field2","message":"field2 is invalid"},{"field":"subObject.field2","message":"another error in the field2"}]
- `invalidFields.field` (string)
  Name of the field. Dot notation is used for nested object field names.
- `invalidFields.message` (string)
  Message field.

## Response 429 fields

- `type` (string)
  Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
  Example: about:blank
- `title` (string)
  Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
  Example: Rate Limit Exceeded
- `status` (integer)
  HTTP status code.
- `detail` (string)
  Human-readable explanation that is specific to this occurrence of the problem.
  Example: A request cannot be executed because the user has sent too many requests within a certain period of time
- `instance` (string)
  URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.