--- updatedAt: 2026-08-25T19:38:29.000Z agentTools: projectIndex: https://loyaltyapi.yotpo.com/llms.txt --- # Record a Custom Action This endpoint records an action performed by a customer. It will apply the action to all active custom action campaigns and award the necessary points and/or discounts. > 📘 Please note: > > The "created *at" parameter will be used in the Get Customer Details call with the "with*history" parameter. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "api-settings", "version": "2.0" }, "servers": [ { "url": "https://loyalty.yotpo.com" } ], "components": { "securitySchemes": { "X-API-KEY": { "type": "apiKey", "in": "header", "name": "X-API-KEY", "description": "Your account API key can be found in the \"Settings\" section of your Yotpo loyalty admin. See [Yotpo Authentication](https://loyaltyapi.yotpo.com/reference/authentication) to learn how to generate your API key." }, "X-GUID": { "type": "apiKey", "in": "header", "name": "X-GUID", "description": "The Globally Unique Identifier found in the \"Settings\" section of your Yotpo loyalty admin. See [Yotpo Authentication](https://loyaltyapi.yotpo.com/reference/authentication) to learn how to generate your GUID." } } }, "security": [ { "X-API-KEY": [], "X-GUID": [] } ], "paths": { "/api/v2/actions": { "post": { "summary": "Record a Custom Action", "description": "This endpoint records an action performed by a customer. It will apply the action to all active custom action campaigns and award the necessary points and/or discounts.", "operationId": "record-a-customer-action", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "customer_email", "action_name" ], "properties": { "type": { "type": "string", "description": "The type of action. Almost always set this to `CustomAction`", "default": "CustomAction" }, "customer_email": { "type": "string", "description": "The email address used to identify the customer who performed the action. Required if no customer_id is passed." }, "customer_id": { "type": "string", "description": "The unique identifier of the customer who performed the action in your system. Required if no customer_email is passed." }, "action_name": { "type": "string", "description": "The name of the action that was performed. This must match the name set for one of your Custom Action Campaigns." }, "ip_address": { "type": "string", "description": "The ip address of the user when the action was performed. This is required if this action completes a referral program requirement." }, "user_agent": { "type": "string", "description": "The browser user agent of the user when the action was performed. This is strongly recommended if this action completes a referral program requirements." }, "created_at": { "type": "string", "description": "The time the action was performed. This will default to the current time. Use this if you need to back date an action." }, "reward_points": { "type": "integer", "description": "Use this to override the normal amount of points awarded for performing the action. Will default to the rules of the campaign otherwise.", "format": "int32" }, "history_title": { "type": "string", "description": "Use this to override the normal description shown to the user in their history. Will default to the campaign settings otherwise." } } }, "examples": { "Body Params": { "value": { "type": "CustomAction", "customer_email": "john@example.com", "action_name": "completed_survey", "ip_address": "127.0.0.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML,like Gecko) Chrome/52.0.2743.116 Safari/537.36", "created_at": "2016-06-28T18:41:13.000Z", "reward_points": "100", "history_title": "Completed Survey" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"id\": null,\n \"created_at\": \"2016-06-28T18:41:13.000Z\",\n \"updated_at\": null,\n \"merchant_id\": 43352,\n \"customer_id\": null,\n \"type\": \"CustomAction\",\n \"referral_id\": null,\n \"ip_address\": \"127.0.0.1\",\n \"user_agent_id\": null,\n \"parent_perk_id\": null,\n \"name\": null\n}" } }, "schema": { "type": "object", "properties": { "id": {}, "created_at": { "type": "string", "example": "2016-06-28T18:41:13.000Z" }, "updated_at": {}, "merchant_id": { "type": "integer", "example": 43352, "default": 0 }, "customer_id": {}, "type": { "type": "string", "example": "CustomAction" }, "referral_id": {}, "ip_address": { "type": "string", "example": "127.0.0.1" }, "user_agent_id": {}, "parent_perk_id": {}, "name": {} } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{}" } }, "schema": { "type": "object", "properties": {} } } } }, "423": { "description": "423", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"errors\": \"Resource is currently being processed. Please try again in a few seconds.\"\n}" } }, "schema": { "type": "object", "properties": { "errors": { "type": "string", "example": "Resource is currently being processed. Please try again in a few seconds." } } } } } } }, "x-internal": false } } }, "x-readme": { "headers": [ { "value": "application/json", "key": "Content-Type" } ], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ``` # Sibling pages * [Adjust a Customer's Point Balance](https://loyaltyapi.yotpo.com/reference/adjust-a-customers-point-balance.md) * [Remove a Customer from an Action Based VIP Tier](https://loyaltyapi.yotpo.com/reference/removing-a-customer-from-an-action-based-vip-tier.md)