> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unibee.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Plan

## Endpoint Overview

**POST** `https://api.unibee.dev/merchant/plan/new`

Create Plan

***

## Authorization

All UniBee Merchant API requests require authentication via API key.

| Header          | Required | Description                           |
| --------------- | -------- | ------------------------------------- |
| `Authorization` | Yes      | Bearer `<your_api_key>`               |
| `Content-Type`  | Yes      | `application/json` (for request body) |

***

## Parameters

Parameters for this endpoint are listed below. The schema is also shown in the Try it panel.

### Request body

| Name                    | Type    | Required | Description                                                                                                            |
| ----------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `addonIds`              | array   | No       | Plan Ids Of Recurring Addon Type                                                                                       |
| `amount`                | integer | Yes      | Plan Amount                                                                                                            |
| `cancelAtTrialEnd`      | integer | No       | whether cancel at subscription first trial end，0-false \| 1-true, will pass to cancelAtPeriodEnd of subscription       |
| `currency`              | string  | Yes      | Plan Currency                                                                                                          |
| `description`           | string  | No       | Description                                                                                                            |
| `externalPlanId`        | string  | No       | ExternalPlanId                                                                                                         |
| `gasPayer`              | string  | No       | who pay the gas for crypto payment, merchant\|user                                                                     |
| `homeUrl`               | string  | No       | HomeUrl,Start With: http                                                                                               |
| `imageUrl`              | string  | No       | ImageUrl,Start With: http                                                                                              |
| `internalName`          | string  | No       |                                                                                                                        |
| `intervalCount`         | integer | No       | Number Of IntervalUnit，em: day\|month\|year\|week                                                                      |
| `intervalUnit`          | string  | No       | Plan Interval Unit，em: day\|month\|year\|week                                                                          |
| `metadata`              | object  | No       | Metadata，Map                                                                                                           |
| `metricLimits`          | array   | No       | Plan's MetricLimit List                                                                                                |
| `metricMeteredCharge`   | array   | No       | Plan's MetricMeteredCharge                                                                                             |
| `metricRecurringCharge` | array   | No       | Plan's MetricRecurringCharge                                                                                           |
| `multiCurrencies`       | array   | No       | Plan's MultiCurrencies                                                                                                 |
| `onetimeAddonIds`       | array   | No       | Plan Ids Of Onetime Addon Type                                                                                         |
| `planName`              | string  | Yes      | Plan Name                                                                                                              |
| `productDescription`    | string  | No       | Default Copy Description                                                                                               |
| `productId`             | integer | No       | Id of product which plan to linked                                                                                     |
| `productName`           | string  | No       | Default Copy PlanName                                                                                                  |
| `trialAmount`           | integer | No       | price of trial period， not available for addon                                                                         |
| `trialDemand`           | string  | No       | demand of trial， not available for addon, example, paymentMethod, payment method will ask for subscription trial start |
| `trialDurationTime`     | integer | No       | duration of trial， not available for addon                                                                             |
| `type`                  | integer | No       | The type of plan, 1-main plan，2-addon plan, 3-onetime plan, default main plan                                          |
| `usVATConfig`           | string  | No       |                                                                                                                        |

***

## Request examples

### cURL

```bash theme={null}
curl -X POST "https://api.unibee.dev/merchant/plan/new" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "addonIds": [],
  "amount": 0,
  "cancelAtTrialEnd": 0,
  "currency": "",
  "description": "",
  "externalPlanId": "id_example",
  "gasPayer": "",
  "homeUrl": "https://example.com",
  "imageUrl": "https://example.com",
  "internalName": "",
  "intervalCount": 0,
  "intervalUnit": "",
  "metadata": {},
  "metricLimits": [],
  "metricMeteredCharge": [],
  "metricRecurringCharge": [],
  "multiCurrencies": [],
  "onetimeAddonIds": 0,
  "planName": "",
  "productDescription": "",
  "productId": 0,
  "productName": "",
  "trialAmount": 0,
  "trialDemand": "",
  "trialDurationTime": 0,
  "type": 0,
  "usVATConfig": ""
}'
```

### Sandbox

```bash theme={null}
curl -X POST "https://api-sandbox.unibee.top/merchant/plan/new" \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "addonIds": [],
  "amount": 0,
  "cancelAtTrialEnd": 0,
  "currency": "",
  "description": "",
  "externalPlanId": "id_example",
  "gasPayer": "",
  "homeUrl": "https://example.com",
  "imageUrl": "https://example.com",
  "internalName": "",
  "intervalCount": 0,
  "intervalUnit": "",
  "metadata": {},
  "metricLimits": [],
  "metricMeteredCharge": [],
  "metricRecurringCharge": [],
  "multiCurrencies": [],
  "onetimeAddonIds": 0,
  "planName": "",
  "productDescription": "",
  "productId": 0,
  "productName": "",
  "trialAmount": 0,
  "trialDemand": "",
  "trialDurationTime": 0,
  "type": 0,
  "usVATConfig": ""
}'
```

***

## Response

Success responses return a JSON envelope with `code`, `data`, `message`, `redirect`, and `requestId`. `code` `0` indicates success.

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| `code`      | integer | Response code. `0` = success |
| `data`      | object  | Response payload             |
| `data.plan` | object  |                              |
| `message`   | string  | Human-readable message       |
| `requestId` | string  | Request ID for support       |

***

## Error handling

| HTTP status | Meaning                                                                   |
| ----------- | ------------------------------------------------------------------------- |
| 400         | Bad request — invalid or missing parameters. Check `message` in the body. |
| 401         | Unauthorized — missing or invalid API key.                                |
| 404         | Not found — invalid path or resource.                                     |
| 500         | Server error — retry with backoff.                                        |

When `code` in the response body is non-zero, check `message` for details. Use `requestId` when contacting support.


## OpenAPI

````yaml post /merchant/plan/new
openapi: 3.0.0
info:
  description: UniBee Api Server
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: OpenAPI UniBee
  version: daily,buildtime:202603161017
servers:
  - url: https://api.unibee.dev
  - url: https://api-sandbox.unibee.top
security:
  - Authorization: []
paths:
  /merchant/plan/new:
    post:
      tags:
        - Plan
      summary: Create Plan
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unibee.api.merchant.plan.NewReq'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  code:
                    format: int
                    properties: {}
                    type: integer
                  data:
                    properties:
                      plan:
                        $ref: '#/components/schemas/unibee.api.bean.Plan'
                    type: object
                  merchantId:
                    format: int64
                    properties: {}
                    type: integer
                  message:
                    format: string
                    properties: {}
                    type: string
                  redirect:
                    format: string
                    properties: {}
                    type: string
                  requestId:
                    format: string
                    properties: {}
                    type: string
                type: object
          description: ''
components:
  schemas:
    unibee.api.merchant.plan.NewReq:
      properties:
        addonIds:
          description: Plan Ids Of Recurring Addon Type
          format: '[]int64'
          items:
            format: int64
            properties: {}
            type: integer
          properties: {}
          type: array
        amount:
          description: Plan Amount
          format: int64
          properties: {}
          type: integer
        cancelAtTrialEnd:
          description: >-
            whether cancel at subscription first trial end，0-false | 1-true,
            will pass to cancelAtPeriodEnd of subscription
          format: int
          properties: {}
          type: integer
        currency:
          description: Plan Currency
          format: string
          properties: {}
          type: string
        description:
          description: Description
          format: string
          properties: {}
          type: string
        externalPlanId:
          description: ExternalPlanId
          format: string
          properties: {}
          type: string
        gasPayer:
          description: who pay the gas for crypto payment, merchant|user
          format: string
          properties: {}
          type: string
        homeUrl:
          description: 'HomeUrl,Start With: http'
          format: string
          properties: {}
          type: string
        imageUrl:
          description: 'ImageUrl,Start With: http'
          format: string
          properties: {}
          type: string
        internalName:
          format: string
          properties: {}
          type: string
        intervalCount:
          description: 'Number Of IntervalUnit，em: day|month|year|week'
          format: int
          properties: {}
          type: integer
        intervalUnit:
          description: 'Plan Interval Unit，em: day|month|year|week'
          format: string
          properties: {}
          type: string
        metadata:
          additionalProperties:
            $ref: '#/components/schemas/interface'
          description: Metadata，Map
          format: map[string]interface {}
          properties: {}
          type: object
        metricLimits:
          description: Plan's MetricLimit List
          format: '[]*bean.PlanMetricLimitParam'
          items:
            $ref: '#/components/schemas/unibee.api.bean.PlanMetricLimitParam'
          properties: {}
          type: array
        metricMeteredCharge:
          description: Plan's MetricMeteredCharge
          format: '[]*bean.PlanMetricMeteredChargeParam'
          items:
            $ref: '#/components/schemas/unibee.api.bean.PlanMetricMeteredChargeParam'
          properties: {}
          type: array
        metricRecurringCharge:
          description: Plan's MetricRecurringCharge
          format: '[]*bean.PlanMetricMeteredChargeParam'
          items:
            $ref: '#/components/schemas/unibee.api.bean.PlanMetricMeteredChargeParam'
          properties: {}
          type: array
        multiCurrencies:
          description: Plan's MultiCurrencies
          format: '[]*bean.PlanMultiCurrency'
          items:
            $ref: '#/components/schemas/unibee.api.bean.PlanMultiCurrency'
          properties: {}
          type: array
        onetimeAddonIds:
          description: Plan Ids Of Onetime Addon Type
          format: '[]int64'
          items:
            format: int64
            properties: {}
            type: integer
          properties: {}
          type: array
        planName:
          description: Plan Name
          format: string
          properties: {}
          type: string
        productDescription:
          description: Default Copy Description
          format: string
          properties: {}
          type: string
        productId:
          description: Id of product which plan to linked
          format: int64
          properties: {}
          type: integer
        productName:
          description: Default Copy PlanName
          format: string
          properties: {}
          type: string
        trialAmount:
          description: price of trial period， not available for addon
          format: int64
          properties: {}
          type: integer
        trialDemand:
          description: >-
            demand of trial， not available for addon, example, paymentMethod,
            payment method will ask for subscription trial start
          format: string
          properties: {}
          type: string
        trialDurationTime:
          description: duration of trial， not available for addon
          format: int64
          properties: {}
          type: integer
        type:
          default: 1
          description: >-
            The type of plan, 1-main plan，2-addon plan, 3-onetime plan, default
            main plan
          format: int
          properties: {}
          type: integer
        usVATConfig:
          $ref: '#/components/schemas/unibee.api.bean.USVATConfig'
      required:
        - planName
        - amount
        - currency
      type: object
    unibee.api.bean.Plan:
      properties:
        amount:
          description: amount, cent, without tax
          format: int64
          properties: {}
          type: integer
        bindingAddonIds:
          description: binded recurring addon planIds，split with ,
          format: string
          properties: {}
          type: string
        bindingOnetimeAddonIds:
          description: binded onetime addon planIds，split with ,
          format: string
          properties: {}
          type: string
        cancelAtTrialEnd:
          description: >-
            whether cancel at subscription first trial end，0-false | 1-true,
            will pass to cancelAtPeriodEnd of subscription
          format: int
          properties: {}
          type: integer
        checkoutUrl:
          description: CheckoutUrl
          format: string
          properties: {}
          type: string
        createTime:
          description: create utc time
          format: int64
          properties: {}
          type: integer
        currency:
          description: currency
          format: string
          properties: {}
          type: string
        description:
          description: description
          format: string
          properties: {}
          type: string
        disableAutoCharge:
          description: disable auto-charge, 0-false,1-true
          format: int
          properties: {}
          type: integer
        externalPlanId:
          description: external_user_id
          format: string
          properties: {}
          type: string
        extraMetricData:
          format: string
          properties: {}
          type: string
        gasPayer:
          description: who pay the gas, merchant|user
          format: string
          properties: {}
          type: string
        homeUrl:
          description: home_url
          format: string
          properties: {}
          type: string
        id:
          format: int64
          properties: {}
          type: integer
        imageUrl:
          description: image_url
          format: string
          properties: {}
          type: string
        internalName:
          description: PlanInternalName
          format: string
          properties: {}
          type: string
        intervalCount:
          description: period unit count
          format: int
          properties: {}
          type: integer
        intervalUnit:
          description: period unit,day|month|year|week
          format: string
          properties: {}
          type: string
        merchantId:
          description: merchant id
          format: int64
          properties: {}
          type: integer
        metadata:
          additionalProperties:
            $ref: '#/components/schemas/interface'
          format: map[string]interface {}
          properties: {}
          type: object
        metricLimits:
          description: Plan's MetricLimit List
          format: '[]*bean.PlanMetricLimitParam'
          items:
            $ref: '#/components/schemas/unibee.api.bean.PlanMetricLimitParam'
          properties: {}
          type: array
        metricMeteredCharge:
          description: Plan's MetricMeteredCharge
          format: '[]*bean.PlanMetricMeteredChargeParam'
          items:
            $ref: '#/components/schemas/unibee.api.bean.PlanMetricMeteredChargeParam'
          properties: {}
          type: array
        metricRecurringCharge:
          description: Plan's MetricRecurringCharge
          format: '[]*bean.PlanMetricMeteredChargeParam'
          items:
            $ref: '#/components/schemas/unibee.api.bean.PlanMetricMeteredChargeParam'
          properties: {}
          type: array
        multiCurrencies:
          description: Plan's MultiCurrencies
          format: '[]*bean.PlanMultiCurrency'
          items:
            $ref: '#/components/schemas/unibee.api.bean.PlanMultiCurrency'
          properties: {}
          type: array
        planName:
          description: PlanName
          format: string
          properties: {}
          type: string
        productId:
          description: product id
          format: int64
          properties: {}
          type: integer
        publishStatus:
          description: 1-UnPublish,2-Publish, Use For Display Plan At UserPortal
          format: int
          properties: {}
          type: integer
        status:
          description: status，1-editing，2-active，3-inactive，4-soft archive, 5-hard archive
          format: int
          properties: {}
          type: integer
        taxPercentage:
          description: TaxPercentage 1000 = 10%
          format: int
          properties: {}
          type: integer
        trialAmount:
          description: price of trial period
          format: int64
          properties: {}
          type: integer
        trialDemand:
          format: string
          properties: {}
          type: string
        trialDurationTime:
          description: duration of trial
          format: int64
          properties: {}
          type: integer
        type:
          description: type，1-main plan，2-addon plan
          format: int
          properties: {}
          type: integer
        usVATConfig:
          $ref: '#/components/schemas/unibee.api.bean.USVATConfig'
      type: object
    interface:
      properties: {}
      type: object
    unibee.api.bean.PlanMetricLimitParam:
      properties:
        metricId:
          description: MetricId
          format: int64
          properties: {}
          type: integer
        metricLimit:
          description: MetricLimit
          format: int64
          properties: {}
          type: integer
      type: object
    unibee.api.bean.PlanMetricMeteredChargeParam:
      properties:
        chargeType:
          description: ChargeType,0-standard pricing 1-graduated pricing
          format: int
          properties: {}
          type: integer
        graduatedAmounts:
          description: GraduatedAmounts, used for graduated pricing
          format: '[]*bean.MetricPlanChargeGraduatedStep'
          items:
            $ref: '#/components/schemas/unibee.api.bean.MetricPlanChargeGraduatedStep'
          properties: {}
          type: array
        metricId:
          description: MetricId
          format: int64
          properties: {}
          type: integer
        standardAmount:
          description: StandardAmount, cent, used for standard pricing,cent
          format: int64
          properties: {}
          type: integer
        standardStartValue:
          description: StandardStartValue, used for standard pricing
          format: int64
          properties: {}
          type: integer
      type: object
    unibee.api.bean.PlanMultiCurrency:
      properties:
        amount:
          description: the amount of exchange rate
          format: int64
          properties: {}
          type: integer
        autoExchange:
          description: >-
            using https://app.exchangerate-api.com/ to update exchange rate if
            true, the exchange APIKey need setup first
          format: bool
          properties: {}
          type: boolean
        currency:
          description: target currency
          format: string
          properties: {}
          type: string
        disable:
          description: disable currency exchange
          format: bool
          properties: {}
          type: boolean
        exchangeRate:
          description: exchange rate, no setup required if AutoExchange is true
          format: float64
          properties: {}
          type: number
      type: object
    unibee.api.bean.USVATConfig:
      properties:
        active:
          format: bool
          properties: {}
          type: boolean
        fromAddress:
          $ref: '#/components/schemas/unibee.api.bean.USAddress'
        nexusAddresses:
          format: '[]*bean.USAddress'
          items:
            $ref: '#/components/schemas/unibee.api.bean.USAddress'
          properties: {}
          type: array
        sellOnUSOnly:
          format: bool
          properties: {}
          type: boolean
        taxCode:
          format: string
          properties: {}
          type: string
        toAddress:
          $ref: '#/components/schemas/unibee.api.bean.USAddress'
      type: object
    unibee.api.bean.MetricPlanChargeGraduatedStep:
      properties:
        endValue:
          description: EndValue, -1 = infinity value(∞)
          format: int64
          properties: {}
          type: integer
        flatAmount:
          description: FlatAmount,cent
          format: int64
          properties: {}
          type: integer
        perAmount:
          description: PerAmount,cent
          format: int64
          properties: {}
          type: integer
        startValue:
          description: StartValue
          format: int64
          properties: {}
          type: integer
      type: object
    unibee.api.bean.USAddress:
      properties:
        address:
          format: string
          properties: {}
          type: string
        city:
          format: string
          properties: {}
          type: string
        countryCode:
          format: string
          properties: {}
          type: string
        state:
          format: string
          properties: {}
          type: string
        verified:
          format: bool
          properties: {}
          type: boolean
        zipCode:
          format: string
          properties: {}
          type: string
      type: object
  securitySchemes:
    Authorization:
      bearerFormat: JWT
      scheme: bearer
      type: http

````