> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # Track Custom Event > To track a custom event, you create an event object. The event object must be linked to the customer who performs the action. If a customer doesn't exist in Voucherify, the customer will be created. ## OpenAPI ````yaml /openapi/events.json post /v1/events openapi: 3.0.1 info: title: Voucherify API - Events version: v2018-08-01 description: >- Voucherify promotion engine REST API. Please see https://docs.voucherify.io/docs for more details. contact: name: Voucherify Team url: https://www.voucherify.io/contact-support email: support@voucherify.io termsOfService: https://www.voucherify.io/legal/subscription-agreement license: name: MIT url: https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE servers: - url: https://{cluster}.voucherify.io description: Base URL variables: cluster: default: api enum: - api - us1.api - as1.api - download - us1.download - as1.download security: [] paths: /v1/events: post: tags: - Events summary: Track Custom Event description: >- To track a custom event, you create an event object. The event object must be linked to the customer who performs the action. If a customer doesn't exist in Voucherify, the customer will be created. operationId: track-custom-event parameters: [] requestBody: description: Specify the details of the custom event. content: application/json: schema: $ref: '#/components/schemas/EventsCreateRequestBody' examples: Example: value: event: event-name customer: source_id: referee-source_id referral: code: voucher-code referrer_id: referrer-source_id Referral triggered by custom event: value: event: user_subscribed customer: source_id: source_customer_event referral: code: 46jL0kYI referrer_id: cust_Vzck5i8U3OhcEUFY6MKhN9Rv metadata: login: bob pricing_plan: PP1 volume_number: 4 Earning rule triggered by custom event: value: event: cart_abandoned customer: source_id: source_customer_event loyalty: code: 6CB4KDAu metadata: date: '2022-12-01' flag: true text: Cart abandoned event date_time: '2022-12-01T09:24:33.061Z' number: 1 required: true responses: '200': description: Returns the event type if the event was received by the application. content: application/json: schema: $ref: '#/components/schemas/EventsCreateResponseBody' examples: Example: value: object: event type: cart_abandoned customer: id: cust_ypePCF6IU6fnUvec6RMXZuH4 name: John Doe email: john@voucherify.io source_id: source_customer_event metadata: prop: value object: customer referral: null loyalty: null '400': description: Returns an error if the request payload is incomplete. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid payload: value: code: 404 key: not_found message: Resource not found details: Cannot find customer with id registered_10055 request_id: v-0dc6ead2680056a15a resource_id: registered_10055 resource_type: customer security: - X-App-Id: [] X-App-Token: [] - X-Voucherify-OAuth: - api - events components: schemas: EventsCreateRequestBody: title: Events Create Request Body type: object description: Request body schema for **POST** `v1/events`. properties: event: type: string description: >- Event name. This is the same name that you used to define a custom event in the **Dashboard** > **Project Settings** > **Event Schema**. minLength: 1 maxLength: 300 customer: description: Customer's information. allOf: - $ref: '#/components/schemas/Customer' referral: type: object description: >- If a **conversion event** for a referral program is set to a custom event, then you need to send the referral code in the payload to make a record of the conversion event. properties: code: type: string description: >- A code through which a new visitor has been referred to a service. referrer_id: type: string description: >- Unique ID of the referring person - it is optional and not required if the referral **code** is provided. example: cust_Vzck5i8U3OhcEUFY6MKhN9Rv required: - code loyalty: type: object description: >- If an earning rule in a loyalty program is based on a custom event. This objects let's you specify the loyalty card to which the custom event should be attributed to. properties: code: type: string description: >- Code of the loyalty card to receive points based on the calculation method defined in the related earning rule. An earning rule is triggered for the loyalty card when the event passed in the `event` parameter of the request payload gets sent along with this loyalty card code. example: L-CARD-BUHuH6g required: - code metadata: type: object description: >- The metadata object stores all custom attributes assigned to the event. A set of key/value pairs that you can attach to an event object. It can be useful for storing additional information about the event in a structured format. Event metadata schema is defined in the **Dashboard** > **Project Settings** > **Event Schema** > **Edit particular event** > **Metadata property definition**. required: - event - customer EventsCreateResponseBody: title: Events Create Response Body type: object description: Response body schema for **POST** `v1/events`. properties: object: type: string default: event description: The object represented is an `event`. enum: - event type: type: string description: The event name. customer: description: A simple customer object allOf: - $ref: '#/components/schemas/SimpleCustomerRequiredObjectType' referral: type: object nullable: true default: null description: A `null` referral object. loyalty: type: object nullable: true default: null description: A `null` loyalty object. metadata: type: object required: - object - type - customer - referral - loyalty - metadata Error: title: Error Object type: object description: Error details properties: code: type: integer description: Error's HTTP status code. key: type: string description: Short string describing the kind of error which occurred. message: type: string description: A human-readable message providing a short description of the error. details: type: string description: A human-readable message providing more details about the error. request_id: type: string example: v-0a885062c80375740f description: >- This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team. resource_id: type: string description: >- Unique resource ID that can be used in another endpoint to get more details. example: rf_0c5d710a87c8a31f86 resource_type: type: string description: The resource type. example: voucher error: type: object description: Includes additional information about the error. properties: message: type: string description: The message configured by the user in a validation rule. required: - code - message Customer: title: Customer allOf: - type: object title: Customer Id And Source Id properties: id: type: string description: The ID of an existing customer. source_id: type: string description: >- A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored. - $ref: '#/components/schemas/CustomerBase' SimpleCustomerRequiredObjectType: type: object description: >- This is an object representing a customer with limited properties used in Event Tracking endpoints. title: Customer Object Required Object Type properties: id: type: string description: The unique ID of a customer that is assigned by Voucherify. example: cust_CSnYd37MXmrbS19XCrghjBsv source_id: type: string description: >- The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service. name: type: string description: Customer's first and last name. email: type: string description: Customer's email address. metadata: type: object description: >- A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments. object: type: string description: >- The type of the object represented by the JSON. This object stores information about the customer. default: customer required: - object CustomerBase: title: Customer Base type: object properties: name: type: string description: Customer's first and last name. description: type: string description: An arbitrary string that you can attach to a customer object. email: type: string description: Customer's email address. phone: type: string description: >- Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel. birthday: type: string description: '`Deprecated`. ~~Customer''s birthdate; format YYYY-MM-DD~~.' format: date birthdate: type: string description: Customer's birthdate; format YYYY-MM-DD. format: date address: type: object nullable: true description: Customer's address. properties: city: type: string description: City state: type: string description: State line_1: type: string description: First line of address. line_2: type: string description: Second line of address. country: type: string description: Country. postal_code: type: string description: Postal code. metadata: type: object description: >- A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments. securitySchemes: X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header X-Voucherify-OAuth: type: oauth2 flows: implicit: authorizationUrl: https://api.voucherify.io/v1/oauth/token scopes: api: Gives access to whole server-side API. vouchers: >- Gives access to all endpoints and methods starting with `v1/vouchers`. client_api: Gives access to whole client-side API. client_vouchers: >- Gives access to all endpoints and methods starting with `/client/v1/vouchers`. promotions: >- Gives access to all endpoints and methods starting with `/v1/promotions`. client_promotions: >- Gives access to all endpoints and methods starting with `/client/v1/promotions` campaigns: >- Gives access to all endpoints and methods starting with `v1/campaigns`. client_publish: >- Gives access to all endpoints and methods starting with `/client/v1/publish`. exports: >- Gives access to all endpoints and methods starting with `/v1/exports`. publications: >- Gives access to all endpoints and methods starting with `/v1/publications`. client_validate: >- Gives access to all endpoints and methods starting with `/client/v1/validate`. validations: >- Gives access to all endpoints and methods starting with `/v1/validations`. client_validations: >- Gives access to all endpoints and methods starting with `/client/v1/validations`. qualifications: >- Gives access to all endpoints and methods starting with `/v1/qualifications`. client_qualifications: >- Gives access to all endpoints and methods starting with `/client/v1/qualifications`. client_redeem: >- Gives access to all endpoints and methods starting with `/client/v1/redeem redemptions: >- Gives access to all endpoints and methods starting with `/v1/redemptions`. client_redemptions: >- Gives access to all endpoints and methods starting with `/client/v1/redemptions` customers: >- Gives access to all endpoints and methods starting with `/v1/customers`. client_customers: >- Gives access to all endpoints and methods starting with `/client/v1/customers`. orders: >- Gives access to all endpoints and methods starting with `/v1/orders`. products: >- Gives access to all endpoints and methods starting with `/v1/products`. skus: >- Gives access to all endpoints and methods starting with `/v1/SKUs`. validation-rules: >- Gives access to all endpoints and methods starting with `/v1/validation-rules`. validation-rules-assignments: >- Gives access to all endpoints and methods starting with `/v1/validation-rules-assignments segments: >- Gives access to all endpoints and methods starting with `/v1/segments`. events: >- Gives access to all endpoints and methods starting with `/v1/events`. client_events: >- Gives access to all endpoints and methods starting with `client/v1/events`. rewards: >- Gives access to all endpoints and methods starting with `/v1/rewards`. assets: >- Gives access to all endpoints and methods starting with `/v1/assets`. task-results: >- Gives access to all endpoints and methods starting with `/v1/task-results`. loyalties: >- Gives access to all endpoints and methods starting with `/v1/loyalties`. client_consents: >- Gives access to all endpoints and methods starting with `client/v1/consents`. consents: >- Gives access to all endpoints and methods starting with `/v1/consents`. async-actions: >- Gives access to all endpoints and methods starting with `/v1/async-actions`. product-collections: >- Gives access to all endpoints and methods starting with `/v1/product-collections`. categories: >- Gives access to all endpoints and methods starting with `/v1/categories`. metadata-schemas: >- Gives access to all endpoints and methods starting with `/v1/metadata-schemas`. locations: >- Gives access to all endpoints and methods starting with `/v1/locations`. referrals: >- Gives access to all endpoints and methods starting with `/v1/referrals`. trash-bin: >- Gives access to all endpoints and methods starting with `/v1/trash-bin`. templates: >- Gives access to all endpoints and methods starting with `/v1/templates`. ````