> ## 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. # New Merchant Metric Event ## Endpoint Overview **POST** `https://api.unibee.dev/merchant/metric/event/new` New Merchant Metric Event *** ## Authorization All UniBee Merchant API requests require authentication via API key. | Header | Required | Description | | --------------- | -------- | ------------------------------------- | | `Authorization` | Yes | Bearer `` | | `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 | | --------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `aggregationUniqueId` | string | No | AggregationUniqueId, valid when AggregationType is count unique. If provided, it has higher priority and will override the value in MetricProperties for the AggregationProperty field | | `aggregationValue` | integer | No | AggregationValue, valid when AggregationType is latest, max or sum. If provided, it has higher priority and will override the value in MetricProperties for the AggregationProperty field | | `email` | string | No | Email， UserId, ExternalUserId, or Email provides one of three options | | `externalEventId` | string | Yes | ExternalEventId, **unique** | | `externalUserId` | string | No | ExternalUserId， UserId, ExternalUserId, or Email provides one of three options | | `metricCode` | string | Yes | MetricCode | | `metricProperties` | string | No | | | `productId` | integer | No | Id of product. Default product will use if productId not specified and subscriptionId is blank | | `userId` | integer | No | UserId， UserId, ExternalUserId, or Email provides one of three options | *** ## Request examples ### cURL ```bash theme={null} curl -X POST "https://api.unibee.dev/merchant/metric/event/new" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "aggregationUniqueId": "id_example", "aggregationValue": 0, "email": "user@example.com", "externalEventId": "id_example", "externalUserId": "id_example", "metricCode": "", "metricProperties": "", "productId": 0, "userId": 0 }' ``` ### Sandbox ```bash theme={null} curl -X POST "https://api-sandbox.unibee.top/merchant/metric/event/new" \ -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "aggregationUniqueId": "id_example", "aggregationValue": 0, "email": "user@example.com", "externalEventId": "id_example", "externalUserId": "id_example", "metricCode": "", "metricProperties": "", "productId": 0, "userId": 0 }' ``` *** ## 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.merchantMetricEvent` | 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/metric/event/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/metric/event/new: post: tags: - Metric Event summary: New Merchant Metric Event requestBody: content: application/json: schema: $ref: '#/components/schemas/unibee.api.merchant.metric.NewEventReq' required: true responses: '200': content: application/json: schema: properties: code: format: int properties: {} type: integer data: properties: merchantMetricEvent: $ref: >- #/components/schemas/unibee.api.bean.MerchantMetricEvent 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.metric.NewEventReq: properties: aggregationUniqueId: description: >- AggregationUniqueId, valid when AggregationType is count unique. If provided, it has higher priority and will override the value in MetricProperties for the AggregationProperty field format: '*string' properties: {} type: string aggregationValue: description: >- AggregationValue, valid when AggregationType is latest, max or sum. If provided, it has higher priority and will override the value in MetricProperties for the AggregationProperty field format: '*int64' properties: {} type: integer email: default: account@unibee.dev description: >- Email， UserId, ExternalUserId, or Email provides one of three options format: string properties: {} type: string externalEventId: description: ExternalEventId, __unique__ format: string properties: {} type: string externalUserId: description: >- ExternalUserId， UserId, ExternalUserId, or Email provides one of three options format: string properties: {} type: string metricCode: description: MetricCode format: string properties: {} type: string metricProperties: $ref: '#/components/schemas/github.com.gogf.gf.v2.encoding.gjson.Json' productId: description: >- Id of product. Default product will use if productId not specified and subscriptionId is blank format: int64 properties: {} type: integer userId: description: >- UserId， UserId, ExternalUserId, or Email provides one of three options format: int64 properties: {} type: integer required: - metricCode - externalEventId type: object unibee.api.bean.MerchantMetricEvent: properties: aggregationPropertyData: description: aggregation property data (Json) format: string properties: {} type: string aggregationPropertyInt: description: aggregation property int, use for metric of max|sum type format: int64 properties: {} type: integer aggregationPropertyString: description: >- aggregation property string, use for metric of count|count_unique type format: string properties: {} type: string chargeInvoiceId: description: charge invoice id format: string properties: {} type: string createTime: description: create utc time format: int64 properties: {} type: integer eventCharge: $ref: '#/components/schemas/unibee.api.bean.EventMetricCharge' externalEventId: description: external_event_id, should be unique format: string properties: {} type: string id: description: Id format: int64 properties: {} type: integer merchantId: description: merchantId format: int64 properties: {} type: integer metricId: description: metric_id format: int64 properties: {} type: integer metricLimit: format: int64 properties: {} type: integer subscriptionIds: format: string properties: {} type: string subscriptionPeriodEnd: description: matched subscription's current_period_end format: int64 properties: {} type: integer subscriptionPeriodStart: description: matched subscription's current_period_start format: int64 properties: {} type: integer used: format: int64 properties: {} type: integer userId: description: user_id format: int64 properties: {} type: integer type: object github.com.gogf.gf.v2.encoding.gjson.Json: properties: {} type: object unibee.api.bean.EventMetricCharge: properties: chargeAmount: description: ChargeAmount format: int64 properties: {} type: integer chargePricing: $ref: '#/components/schemas/unibee.api.bean.PlanMetricMeteredChargeParam' currency: description: Currency format: string properties: {} type: string currentValue: description: CurrentUsedValue format: int64 properties: {} type: integer graduatedStep: $ref: '#/components/schemas/unibee.api.bean.MetricPlanChargeGraduatedStep' planId: description: PlanId format: int64 properties: {} type: integer totalChargeAmount: description: TotalChargeAmount format: int64 properties: {} type: integer unitAmount: description: UnitAmount 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.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 securitySchemes: Authorization: bearerFormat: JWT scheme: bearer type: http ````