Plans

Use pricing plans to describe how the customer must pay for products.

Rebilly provides the following plan types:

  • Trial only: Use this plan to create and offer a free or discounted trial period for your product. For example, a free 2 week trial of an internet service. After the trial, the customer can choose to sign up for a paid subscription, or stop using the service.
  • Recurring: Use this plan to create and offer a subscription for your product. For example, a monthly subscription to an internet service that is charged at 20 USD per month.
  • One time sale: Use this plan to create and offer a one-off sale for your products. For example, a one time purchase of two bags of coffee.

For information on the plans resource, see Plans.

For information on plan pricing, see Pricing formulas.

Operations

Retrieve plans

Request

Retrieves a list of plans.

To retrieve plans by type, use filter=type:{type}, where {type} is subscription, one-time-sale, or trial-only. To retrieve plans of several types, separate the types with commas, for example: filter=type:one-time-sale,trial-only. Other type values, including negated values such as type:!subscription, match no plans.

Security
SecretApiKey or JWT or ApplicationJWT
Query
filterstring

Criteria for filtering collection items. This field requires a special format. Use , to specify multiple allowed values. Use ; to specify multiple fields.

For more information, see Search filters.

sortArray of strings

Sorts and orders the collection of items. To sort in descending order, prefix with -. Multiple fields can be sorted by separating each with ,.

limitinteger, [ 0 .. 1000 ]

Limit the number of collection items to be returned. Use 0 to return an empty collection and still receive the count of matching items in Pagination-Total.

offsetinteger, [ 0 .. 1000 ]
Specifies the starting point within the collection of items to be returned.
qstring
Use this field to perform a partial search of text fields.
curl -i -X GET \
  'https://www.rebilly.com/_mock/catalog/all/plans?filter=string&sort=string&limit=0&offset=0&q=string' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE'

Responses

List of plans retrieved.
Headers
Pagination-Totalinteger

Total number of items that match the request. The value is independent of limit, including when limit is 0.

Example:332
Pagination-Limitinteger
Maximum number of items per page.
Example:100
Pagination-Offsetinteger

Specifies the starting point within the collection of resource results. For example, a request with limit=20 retrieves and displays the first 20 results on a page. A following request with limit=20 and offset=20, retrieves the next page of 20 results.

Example:2
Bodyapplication/json
Array [
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:
{
  "region": "US",
  "size": "xxl"
}
currencystring, = 3 characters(CurrencyCode)required
Currency code in ISO 4217 format.
Example:"USD"
currencySignstringread-only
Currency sign.
pricingobject(PlanPriceFormula)required
setupFeenumber or null, (double), >= 0(PlanSetupFee)

One-time setup fee charged when the plan starts. Set to 0 or null if no setup fee applies.

Example:0
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.
_linksArray of objectsread-only
Related links.
setupobject or null(PlanSetup)deprecated
Setup fee information for the plan.
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": { … },
    "currency": "USD",
    "currencySign": "string",
    "pricing": { … },
    "setup": { … },
    "setupFee": 0,
    "customFields": { … },
    "isActive": true,
    "revision": 0,
    "isTrialOnly": false,
    "recurringInterval": { … },
    "trial": { … },
    "meteredBilling": { … },
    "invoiceTimeShift": { … },
    "createdTime": "2019-08-24T14:15:22Z",
    "updatedTime": "2019-08-24T14:15:22Z",
    "_links": [ … ]
  }
]