/
Create a plan

Create a plan

Request

Creates a plan.

Security
SecretApiKey or JWT
Bodyapplication/jsonrequired

Plan resource.

One of:

Details of the subscription order plan. Use this plan for subscriptions or sales that reoccur over a period of time.

typestring

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.

Value:"subscription"
namestring, <= 255 charactersrequired

Name of the plan. This name is displayed on invoices and receipts.

descriptionstring, <= 65535 characters

Plain-text description of the plan. This field accepts plain-text only.

richDescriptionstring, <= 65535 characters

Rich-text description of the plan. This field accepts rich text formatting, such as: bold, underline, italic, and hyperlinks.

productIdstring, <= 50 charactersrequired

ID of the related product.

Example:"prod_0YV7DES3WPC5J8JD8QTVNZBZNZ"
productOptionsobject or null

Name-value pairs that specify the product options.

Example:
{
  "color": "red",
  "size": "xxl"
}
currencystring, = 3 characters(CurrencyCode)required

Currency code in ISO 4217 format.

Example:"USD"
pricingobject(PlanPriceFormula)required
setupobject or null(PlanSetup)

Setup fee information for the plan.

customFieldsobject(ResourceCustomFields)

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.

Default:{}
Example:
{
  "foo": "bar"
}
isActiveboolean

Specifies if the plan is active.

Default:true
recurringIntervalobjectrequired

Service interval settings.

trialobject or null(PlanTrial)

Trial configuration setting. If you do not want to offer a trial, set this value to null.

meteredBillingobject or 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.

curl -i -X POST \
  https://www.rebilly.com/_mock/catalog/all/plans \
  -H 'Content-Type: application/json' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE' \
  -d '{
    "type": "subscription",
    "name": "string",
    "description": "string",
    "richDescription": "string",
    "productId": "prod_0YV7DES3WPC5J8JD8QTVNZBZNZ",
    "productOptions": {
      "color": "red",
      "size": "xxl"
    },
    "currency": "USD",
    "pricing": {
      "formula": "fixed-fee",
      "price": 99.95
    },
    "setup": {
      "price": 0.1
    },
    "customFields": {
      "foo": "bar"
    },
    "isActive": true,
    "recurringInterval": {
      "periodAnchorInstruction": {
        "method": "day-of-month",
        "day": 1,
        "time": "14:15:22Z"
      },
      "unit": "day",
      "length": 1,
      "limit": 1,
      "billingTiming": "prepaid"
    },
    "trial": {
      "price": 0.1,
      "period": {
        "unit": "day",
        "length": 1
      }
    },
    "meteredBilling": {
      "strategy": "sum",
      "min": 0.01,
      "max": 0.01,
      "sticky": false
    },
    "invoiceTimeShift": {
      "issueTimeShift": {
        "chronology": "before",
        "duration": 1,
        "unit": "second"
      },
      "dueTimeShift": {
        "duration": 1,
        "unit": "hour"
      }
    }
  }'

Responses

Plan created.

Headers
Locationstring, (uri)

Location of the related resource.

Example:"https://api.rebilly.com/example"
X-RateLimit-Limitinteger

Total number of rate limit tokens for this request within a rate limit period. For more information, see Rate limits.

Example:3600
X-RateLimit-Remaininginteger

Remaining number of rate limit tokens for this request within the rate limit period. For example, in the sandbox environment, rate limits for non-GET endpoints are set at 3000 requests per 10 minutes.

Example:3600
Bodyapplication/json
idstring, <= 50 charactersread-onlyrequired

ID of the plan.

Example:"plan_0YV7DENSVGDBW9S71XZNNYYQ0X"
typestringrequired

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.

Value:"subscription"
Discriminator
namestring, <= 255 charactersrequired

Name of the plan. This name is displayed on invoices and receipts.

descriptionstring, <= 65535 characters

Plain-text description of the plan. This field accepts plain-text only.

richDescriptionstring, <= 65535 characters

Rich-text description of the plan. This field accepts rich text formatting, such as: bold, underline, italic, and hyperlinks.

productIdstring, <= 50 charactersrequired

ID of the related product.

Example:"prod_0YV7DES3WPC5J8JD8QTVNZBZNZ"
productOptionsobject or null

Name-value pairs that specify the product options.

Example:
{
  "color": "red",
  "size": "xxl"
}
currencystring, = 3 characters(CurrencyCode)required

Currency code in ISO 4217 format.

Example:"USD"
currencySignstringread-only

Currency sign.

pricingobject(PlanPriceFormula)required
setupobject or null(PlanSetup)

Setup fee information for the plan.

customFieldsobject(ResourceCustomFields)

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.

Default:{}
Example:
{
  "foo": "bar"
}
isActiveboolean

Specifies if the plan is active.

Default:true
revisionintegerread-only

Number of times the plan is modified. Compare this value with materialized subscription item revision values.

isTrialOnlybooleanread-only

Specifies if a plan is a trial that does not have recurring instructions.

Value:false
recurringIntervalobjectrequired

Service interval settings.

trialobject or null(PlanTrial)

Trial configuration setting. If you do not want to offer a trial, set this value to null.

meteredBillingobject or 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.

createdTimestring, (date-time)(CreatedTime)read-only

Date and time when the resource is created. This value is set automatically when the resource is created.

updatedTimestring, (date-time)(UpdatedTime)read-only

Date and time when the resource is updated. This value is set automatically when the resource is updated.

invoiceTimeShiftobject or null(InvoiceTimeShift)read-onlydeprecated

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.
Response
{
  "id": "plan_0YV7DENSVGDBW9S71XZNNYYQ0X",
  "type": "subscription",
  "name": "string",
  "description": "string",
  "richDescription": "string",
  "productId": "prod_0YV7DES3WPC5J8JD8QTVNZBZNZ",
  "productOptions": {
    "color": "red",
    "size": "xxl"
  },
  "currency": "USD",
  "currencySign": "string",
  "pricing": {
    "formula": "fixed-fee",
    "price": 99.95
  },
  "setup": {
    "price": 0.1
  },
  "customFields": {
    "foo": "bar"
  },
  "isActive": true,
  "revision": 0,
  "isTrialOnly": false,
  "recurringInterval": {
    "periodAnchorInstruction": { … },
    "unit": "day",
    "length": 1,
    "limit": 1,
    "billingTiming": "prepaid"
  },
  "trial": {
    "price": 0.1,
    "period": { … }
  },
  "meteredBilling": {
    "strategy": "sum",
    "min": 0.01,
    "max": 0.01,
    "sticky": false
  },
  "invoiceTimeShift": {
    "issueTimeShift": { … },
    "dueTimeShift": { … }
  },
  "createdTime": "2019-08-24T14:15:22Z",
  "updatedTime": "2019-08-24T14:15:22Z",
  "_links": [
    { … }
  ]
}