{ "openapi": "3.0.0", "info": { "title": "Merchant API", "description": "Interact directly with the Mention Me platform using our REST API.", "termsOfService": "https://mention-me.com/help/tnc_f/site", "contact": { "name": "Mention Me", "url": "https://mention-me.com", "email": "support@mention-me.com" }, "version": "v2" }, "servers": [ { "url": "https://mention-me.com", "description": "Production" }, { "url": "https://demo.mention-me.com", "description": "Demo" } ], "paths": { "/api/merchant/v2/coupons/validate/{coupon_code}": { "get": { "tags": [ "Coupons" ], "summary": "Validate coupon code", "description": "Check whether a single-use coupon code is valid and return details about the reward it is allowed to be redeemed for.\n\nIn this case we assume that Mention Me has issued a coupon to a customer or potential customer. This coupon could be a single-use coupon previously given to Mention Me in a batch of coupons. Or it could be a single-use coupon generated directly by Mention Me.\n\nThe customer could have been promised the reward as a potential new customer (referee), for referring another customer (referrer) or just because they've been offered an incentive to come to store (incentive for action).\n\nThe customer then brings the coupon to the merchant intending to redeem it. This endpoint allows the merchant (or a third party) to check if the coupon is still valid and is capable of being used to redeem a reward at Mention Me.\n\nThis endpoint allows you to validate a coupon code before attempting to redeem it. It will check:\n\n\n- Whether the coupon exists for your merchant\n\n- Whether the coupon is currently valid (not expired, not barred, has started)\n\n- Whether the coupon is attached to an unredeemed reward and hence can be spent\n\n\nThere are three responses (validityResponseCode):\n\n - FOUND_REDEEMABLE - this means the coupon is found, is valid and can be used to spend the provided reward.\n\n - FOUND_NOT_REDEEMABLE - this means the coupon is known to Mention Me - but is either not valid or has already been spent.\n\n - NOT_FOUND - the coupon is not known to Mention Me.\n\n\nThere is also a human-readable description of the response code (validityResponseDescription). Use the validityResponseCode to decide on the outcome (the human-readable description could change).\n\nIf the coupon is found, the response will include details about the reward such as the discount amount, type (e.g., percentage or fixed amount), currency, and description.\n\nIf the coupon is not redeemable, the validityResponseDescription will indicate why it cannot be used.\n\nIf the coupon is not found, the response won't have additional details.\n\nIf you find the coupon is valid and then allow the customer to redeem the coupon you should then subsequently tell us about the purchase they made, including the coupon code so that we can mark it as redeemed. Once you've done that the coupon will of course be invalid if requested again.\n\nYou can do this using the Record Order API endpoint (if you have the email address of the customer) or the Redeem Coupon API endpoint (if you don't have the email address of the customer).\n\n**Scopes:** `customers:read`, `rewards:read`\n\n**Rate limits:** 300 requests per 5 minutes. Shared across all 'coupons' endpoints.", "operationId": "get_merchant_api_coupons_validate", "parameters": [ { "name": "coupon_code", "in": "path", "description": "The coupon code to validate", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Coupon validation result with reward details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponValidationOutput" } } } }, "401": { "description": "Required scopes are missing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorisedRFC7807Problem" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsRFC7807Problem" } } } } } } }, "/api/merchant/v2/customers": { "post": { "tags": [ "Customers" ], "summary": "Get customers", "description": "Returns all customers who match the given set of filters.\n\nWhen filtering by Customer Id, every customer who matches the identifier will be returned.\n\nWhen filtering by Email, because it is unique, one customer will be returned for each matching identifier.\n\nIf we cannot find a customer provided, we will not include them in the response.\n\nIf none of the customers provided can be found, we will return a 404.\n\nYou may send 100 customers per request.\n\n**Scopes:** `customers:read`\n\n**Rate limits:** 300 requests per 5 minutes. Shared across all 'customers' endpoints.", "operationId": "post_merchant_api_customers_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerIdentifierCollectionInput" } } } }, "responses": { "200": { "description": "All customers who matched the identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPayloadCollectionOutput" } } } }, "401": { "description": "Required scopes are missing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorisedRFC7807Problem" } } } }, "404": { "description": "No customers matched the identifiers.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RFC7807Problem" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsRFC7807Problem" } } } } } }, "delete": { "tags": [ "Customers" ], "summary": "Purge customers", "description": "Purge all customers matching the given identifiers.\n\nPurging is a permanent action. Once a customer is purged, they cannot be recovered.\n\nPurging is done on a queue. It may take some time for the customers to be purged. We recommend using the `GET /v2/customers` endpoint to determine if the customers have been purged. Approximate time to purge is\nnormally under < 5 minutes, but can be several hours in some cases.\n\nCustomers who we were able to queue will be returned in the `accepted` array. Customers who we do not hold a record of or cannot find will be returned in the `errors` array.\n\n**Scopes:** `customers:delete`\n\n**Rate limits:** 300 requests per 5 minutes. Shared across all 'customers' endpoints.", "operationId": "delete_merchant_api_customers_delete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerIdentifierCollectionInput" } } } }, "responses": { "202": { "description": "All identifiers that were queued to be purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCustomerResponse" } } } }, "401": { "description": "Required scopes are missing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorisedRFC7807Problem" } } } }, "404": { "description": "No customers matched the identifiers.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RFC7807Problem" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsRFC7807Problem" } } } } } } }, "/api/merchant/v2/customers/lapse": { "post": { "tags": [ "Customers" ], "summary": "Lapse customers", "description": "A customer who is lapsed is one who you no longer consider an existing customer. This can be used to allow the customer to be referred again. A common use case for this is in subscription businesses where a customer has cancelled their subscription and is no longer a customer - you can mark them as lapsed to enable them to be re-introduced.\n\nLapsing is a permanent action. It can be reversed by recording a new transaction for the customer.\n\nLapsing is done on a queue. It may take some time for the customers to be recorded as lapsed. We recommend using the `GET /v2/customers` endpoint to determine if the customer is active or not. Approximate time to lapse is\nnormally under < 5 minutes, but can be several hours in some cases.\n\nCustomers who we were able to queue will be returned in the `accepted` array. Customers who we do not hold a record of or cannot find will be returned in the `errors` array.\n\n**Scopes:** `customers:write`\n\n**Rate limits:** 300 requests per 5 minutes. Shared across all 'customers' endpoints.", "operationId": "post_merchant_api_customers_lapse", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerIdentifierCollectionInput" } } } }, "responses": { "202": { "description": "All identifiers that were queued to be marked as lapsed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCustomerResponse" } } } }, "401": { "description": "Required scopes are missing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorisedRFC7807Problem" } } } }, "404": { "description": "No customers matched the identifiers.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RFC7807Problem" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsRFC7807Problem" } } } } } } }, "/api/merchant/v2/customers/rewards": { "post": { "tags": [ "Customers" ], "summary": "Get customer rewards", "description": "Returns all rewards a customer has been given.\n\nRewards that are fulfilled outside of Mention Me will not be returned.\n\n**Scopes:** `customers:read`, `rewards:read`\n\n**Rate limits:** 300 requests per 5 minutes. Shared across all 'rewards' endpoints.", "operationId": "post_merchant_api_rewards_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEmailIdentifierInput" } } } }, "responses": { "200": { "description": "The rewards issued to the customer matching the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRewardsOutput" } } } }, "401": { "description": "Required scopes are missing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorisedRFC7807Problem" } } } }, "404": { "description": "No customers matched the identifier.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RFC7807Problem" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsRFC7807Problem" } } } } } } }, "/api/merchant/v2/referee/cancellation": { "post": { "tags": [ "Referee" ], "summary": "Referee cancellations", "description": "Mark all customers matching the given identifiers as cancelled. i.e. they've cancelled their order or have failed to fulfil all necessary steps in order to be given a reward.\n\nOnly customers who could be eligible for a reward will be marked as cancelled. Any other customers included\n(e.g. customers who might order in the future) will be ignored and discarded.\n\nWe strongly suggest you pass us _all_ customers who cancelled - as you may not know who was introduced by a friend. We will discard any customers details who do not need cancellation.\n\nCancellation is completed on a queue. It may take some time for the customers to be marked as cancelled. Approximate time to mark someone as cancelled is normally under < 5 minutes, but can be several hours in some cases.\n\nCustomers who we were able to queue will be returned in the `accepted` array. Customers who we do not hold a record of or cannot find will be returned in the `errors` array.\n\nYou may send 100 customers per request.\n\n**Scopes:** `customers:write`\n\n**Rate limits:** 300 requests per 5 minutes. Shared across all 'referee' endpoints.", "operationId": "post_merchant_api_referee_cancellation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEmailIdentifierCollectionInput" } } } }, "responses": { "202": { "description": "All identifiers that were queued to be marked as cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCustomerResponse" } } } }, "401": { "description": "Required scopes are missing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorisedRFC7807Problem" } } } }, "404": { "description": "No customers matched the identifiers.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RFC7807Problem" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsRFC7807Problem" } } } } } } }, "/api/merchant/v2/referee/eligibility": { "post": { "tags": [ "Referee" ], "summary": "Referee eligibility", "description": "Mark all customers matching the given identifiers as eligible for a reward - i.e. they've completed all necessary steps in order to be given a reward. For instance, this could be keeping a product for a certain amount of time, completing their first month with a subscription or completing transferring provider for a utility.\n\nOnly customers who are eligible for a reward will be marked as eligible. Any other customers included (e.g. customers who were not referred by a friend or those who do not require approval) will be ignored and discarded.\n\nCustomers who require approval because they are suspected of gaming the program will not be marked as eligible. You can approve the customers in the Merchant Portal.\n\nWe strongly suggest you pass us _all_ customers who complete the eligibility criteria - as you may not know who was introduced by a friend. We will discard any customers details who are not eligible.\n\nEligibility is completed on a queue. It may take some time for the customers to be marked as eligible. Approximate time to mark someone as eligible is normally under < 5 minutes, but can be several hours in some cases.\n\nCustomers who we were able to queue will be returned in the `accepted` array. Customers who we do not hold a record of or cannot find will be returned in the `errors` array.\n\nYou may send 100 customers per request.\n\n**Scopes:** `customers:write`\n\n**Rate limits:** 300 requests per 5 minutes. Shared across all 'referee' endpoints.", "operationId": "post_merchant_api_referee_eligibility", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEmailIdentifierCollectionInput" } } } }, "responses": { "202": { "description": "All identifiers that were queued to be marked as eligible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCustomerResponse" } } } }, "401": { "description": "Required scopes are missing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorisedRFC7807Problem" } } } }, "404": { "description": "No customers matched the identifiers.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RFC7807Problem" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsRFC7807Problem" } } } } } } } }, "components": { "schemas": { "RequestAuthentication": { "required": [ "partnerCode", "situation", "authenticationToken", "localeCode" ], "properties": { "partnerCode": { "description": "Your partner code, used to link to your users and offers", "type": "string", "example": "[YOUR-PARTNER-CODE]" }, "situation": { "description": "Situation - a string representing where in the application you are making this request", "type": "string", "example": "mobile-app" }, "segment": { "description": "Segment - the segment the customer belongs to", "type": "string", "example": "vip" }, "localeCode": { "description": "Locale code - ISO standard locale code (e.g. en_GB) for the locale you expect the content to be in", "type": "string", "example": "en_GB" }, "ipAddress": { "description": "IP address of the customer connection. If you're making a request on behalf of a customer, pass their IP address here. If the customer will connect directly, leave this empty and we will retrieve this from their request.", "type": "string", "example": "127.0.0.1" }, "userDeviceIdentifier": { "description": "User Device Identifier should be a unique reference to this device. We use this for preventing gaming. Multiple users with the same Device Identifier will be treated as the same individual and may be flagged for gaming. On Android the UniqueID could be an InstanceID or GUID. On iPhone the UniqueID should be generated by identifierForVendor.", "type": "string", "example": "" }, "deviceType": { "description": "Device type - your description of the device the user is using. We use this for performance and conversion optimisation.", "type": "string", "example": "" }, "appName": { "description": "Your application name. Used for reporting.", "type": "string", "example": "" }, "appVersion": { "description": "Your application version reference. Used for reporting and troubleshooting.", "type": "string", "example": "e.g. MyApp/v1.73" }, "authenticationToken": { "description": "This is a signature using a salted hash of the email address of the customer with a secret key, and validates the authenticity of the request.\n\nFor information on how to correctly generate this token, please see the documentation: https://docs.mention-me.com/api-reference/entry-point-api/authentication-token", "type": "string", "example": "" } }, "type": "object" }, "Referee": { "properties": { "emailAddress": { "description": "Customer email address", "type": "string", "example": "" }, "title": { "description": "Customer title such as Mr, Miss, Dr or Sir", "type": "string", "example": "" }, "firstname": { "description": "Customer firstname", "type": "string", "example": "" }, "surname": { "description": "Customer surname", "type": "string", "example": "" }, "uniqueIdentifier": { "description": "Your unique identifier for this customer e.g. CustomerId", "type": "string", "example": "" } }, "type": "object" }, "RequestWithVariation": { "required": [ "partnerCode", "situation", "localeCode" ], "properties": { "partnerCode": { "description": "Your partner code, used to link to your users and offers", "type": "string", "example": "[YOUR-PARTNER-CODE]" }, "situation": { "description": "Situation - a string representing where in the application you are making this request", "type": "string", "example": "mobile-app" }, "segment": { "description": "Segment - the segment the customer belongs to", "type": "string", "example": "vip" }, "localeCode": { "description": "Locale code - ISO standard locale code (e.g. en_GB) for the locale you expect the content to be in", "type": "string", "example": "en_GB" }, "ipAddress": { "description": "IP address of the customer connection. If you're making a request on behalf of a customer, pass their IP address here. If the customer will connect directly, leave this empty and we will retrieve this from their request.", "type": "string", "example": "127.0.0.1" }, "userDeviceIdentifier": { "description": "User Device Identifier should be a unique reference to this device. We use this for preventing gaming. Multiple users with the same Device Identifier will be treated as the same individual and may be flagged for gaming. On Android the UniqueID could be an InstanceID or GUID. On iPhone the UniqueID should be generated by identifierForVendor.", "type": "string", "example": "" }, "deviceType": { "description": "Device type - your description of the device the user is using. We use this for performance and conversion optimisation.", "type": "string", "example": "" }, "appName": { "description": "Your application name. Used for reporting.", "type": "string", "example": "" }, "appVersion": { "description": "Your application version reference. Used for reporting and troubleshooting.", "type": "string", "example": "e.g. MyApp/v1.73" }, "variation": { "description": "Variation - an index (0,1,2...) specifying which of the currently running AB tests to choose (if available)", "type": "string", "example": "" } }, "type": "object" }, "Request": { "required": [ "partnerCode", "situation", "localeCode" ], "properties": { "partnerCode": { "description": "Your partner code, used to link to your users and offers", "type": "string", "example": "[YOUR-PARTNER-CODE]" }, "situation": { "description": "Situation - a string representing where in the application you are making this request", "type": "string", "example": "mobile-app" }, "segment": { "description": "Segment - the segment the customer belongs to", "type": "string", "example": "vip" }, "localeCode": { "description": "Locale code - ISO standard locale code (e.g. en_GB) for the locale you expect the content to be in", "type": "string", "example": "en_GB" }, "ipAddress": { "description": "IP address of the customer connection. If you're making a request on behalf of a customer, pass their IP address here. If the customer will connect directly, leave this empty and we will retrieve this from their request.", "type": "string", "example": "127.0.0.1" }, "userDeviceIdentifier": { "description": "User Device Identifier should be a unique reference to this device. We use this for preventing gaming. Multiple users with the same Device Identifier will be treated as the same individual and may be flagged for gaming. On Android the UniqueID could be an InstanceID or GUID. On iPhone the UniqueID should be generated by identifierForVendor.", "type": "string", "example": "" }, "deviceType": { "description": "Device type - your description of the device the user is using. We use this for performance and conversion optimisation.", "type": "string", "example": "" }, "appName": { "description": "Your application name. Used for reporting.", "type": "string", "example": "" }, "appVersion": { "description": "Your application version reference. Used for reporting and troubleshooting.", "type": "string", "example": "e.g. MyApp/v1.73" } }, "type": "object" }, "OrderDetails": { "required": [ "orderIdentifier", "total", "currencyCode", "dateString" ], "properties": { "orderIdentifier": { "description": "Your Order Identifier for the transaction that has taken place", "type": "string", "example": "123456" }, "total": { "description": "Order subtotal, excluding tax and shipping in the currency specified by currencyCode", "type": "string", "example": "100" }, "currencyCode": { "description": "3 letter currency code for the currency in which the transaction took place. Use the ISO4217 format (e.g. GBP, EUR, etc", "type": "string", "example": "GBP" }, "dateString": { "description": "The date on which the transaction took place (typically the current date/time). Use ISO8601 format (e.g. 2016-11-30T17:52:50Z)", "type": "string", "example": "2026-01-01T12:00:00+00:00" }, "couponCode": { "description": "If a coupon was used in the transaction, the coupon code the consumer used. If multiple coupons were used, pass them as a comma separated list. Leave blank if no coupon was used.", "type": "string", "example": "ABC23252" }, "discountAmount": { "description": "The discount amount. Our assumption is this has already been taken off the order subtotal provided. This allows us to calculate the Cost Per Acquisition for referral.", "type": "string", "example": "12.44" }, "orderItemCount": { "description": "The number of items in the order/cart (if applicable). This helps us understand the type of purchase and can be a signal of advocacy.", "type": "string", "example": "3" }, "isSubscription": { "description": "Whether this order is for a subscription (recurring). This helps us qualify and categorise the revenue.", "type": "boolean", "example": "" }, "isGift": { "description": "Whether this order is a gift (being bought for someone else). Gifts can be signals of advocacy.", "type": "boolean", "example": "" } }, "type": "object" }, "ImplementationDetails": { "properties": { "wrapContentWithBranding": { "description": "If true (default), serve content in the URLs with customisable branding wrapper (normally a logo and padding). If false, serve content without any wrapping. ", "type": "boolean", "example": true }, "showCloseIcon": { "description": "If true (and the page is rendered inside an iframe), Mention Me will include a close icon. A user clicking on the close icon will trigger a postMessage event which can be listened to for closing the iframe. Documentation is available at https://docs.mention-me.com/developer-docs/advanced/postmessage-iframe", "type": "boolean", "example": false } }, "type": "object" }, "CustomerEnrolling": { "required": [ "emailAddress", "firstname", "surname" ], "properties": { "emailAddress": { "description": "Customer email address", "type": "string", "example": "jane.doe@example.com" }, "title": { "description": "Customer title such as Mr, Miss, Dr or Sir", "type": "string", "example": "" }, "firstname": { "description": "Customer firstname", "type": "string", "example": "" }, "surname": { "description": "Customer surname", "type": "string", "example": "" }, "uniqueIdentifier": { "description": "Your unique identifier for this customer e.g. CustomerId", "type": "string", "example": "" }, "segment": { "description": "Customer segment - a string containing segment data about this customer, e.g. vip or employee. You can concatenate multiple segments together if you wish using hyphens.", "type": "string", "example": "" }, "customField": { "description": "Custom field - a string containing custom data about this customer, e.g. SEGMENT001 or Package B", "type": "string", "example": "" }, "visitorId": { "description": "The visitor ID from the MentionMe Browser Fingerprint, used to link customer journeys. This should be a SHA256 hash (browserId + clientIP).", "type": "string", "example": "" }, "hasEngaged": { "description": "Has this customer been informed of their privacy rights, and actively engaged in the offer? Mention Me expects you to set this as false when you first show the offer, and true when someone has actively engaged, e.g. after clicking a call to action. If no value is provided, we will use the default defined on the offer.", "type": "boolean", "example": false } }, "type": "object" }, "CustomerDetails": { "required": [ "emailAddress", "firstname", "surname" ], "properties": { "emailAddress": { "description": "Customer email address", "type": "string", "example": "jane.doe@example.com" }, "title": { "description": "Customer title such as Mr, Miss, Dr or Sir", "type": "string", "example": "" }, "firstname": { "description": "Customer firstname", "type": "string", "example": "" }, "surname": { "description": "Customer surname", "type": "string", "example": "" }, "uniqueIdentifier": { "description": "Your unique identifier for this customer e.g. CustomerId", "type": "string", "example": "" }, "segment": { "description": "Customer segment - a string containing segment data about this customer, e.g. vip or employee. You can concatenate multiple segments together if you wish using hyphens.", "type": "string", "example": "" }, "customField": { "description": "Custom field - a string containing custom data about this customer, e.g. SEGMENT001 or Package B", "type": "string", "example": "" }, "visitorId": { "description": "The visitor ID from the MentionMe Browser Fingerprint, used to link customer journeys. This should be a SHA256 hash (browserId + clientIP).", "type": "string", "example": "" } }, "type": "object" }, "Address": { "properties": { "addressLine1": { "description": "First line of address", "type": "string", "example": "" }, "addressLine2": { "description": "Second line of address", "type": "string", "example": "" }, "addressCity": { "description": "City part of address", "type": "string", "example": "" }, "addressCounty": { "description": "County or state part of address", "type": "string", "example": "" }, "addressPostCode": { "description": "Post or ZIP code", "type": "string", "example": "" }, "addressCountry": { "description": "Country of address", "type": "string", "example": "" } }, "type": "object" }, "AddressWithCountry": { "properties": { "addressCountry": { "description": "Country of address e.g. UK or France", "type": "string", "example": "" } }, "type": "object" }, "CouponValidationOutput": { "description": "Validation status and reward details for a coupon code", "required": [ "validityResponseCode" ], "properties": { "validityResponseCode": { "description": "System readable code indicating whether the coupon code is FOUND_REDEEMABLE, FOUND_NOT_REDEEMABLE or NOT_FOUND", "type": "string" }, "validityResponseDescription": { "description": "Human readable response indicating information about the code", "type": "string", "default": null, "nullable": true }, "rewardType": { "description": "The type of reward (AMOUNT, PERCENTAGE, etc.)", "type": "string", "default": null, "nullable": true }, "rewardAmount": { "description": "The amount or percentage value of the reward", "type": "number", "format": "float", "default": null, "nullable": true }, "currencyCode": { "description": "The currency code for the reward (e.g., GBP, USD)", "type": "string", "default": null, "nullable": true }, "description": { "description": "Human-readable description of the reward", "type": "string", "default": null, "nullable": true } }, "type": "object" }, "UnauthorisedRFC7807Problem": { "properties": { "status": { "type": "integer", "maximum": 599, "minimum": 200, "example": 401 }, "type": { "type": "string", "example": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }, "title": { "type": "string", "example": "Unauthorized" }, "detail": { "type": "string", "example": "Missing at least one of the required scopes" } }, "type": "object" }, "TooManyRequestsRFC7807Problem": { "properties": { "status": { "type": "integer", "maximum": 599, "minimum": 200, "example": 401 }, "type": { "type": "string", "example": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }, "title": { "type": "string", "example": "Too Many Requests" }, "detail": { "type": "string", "example": "Rate limit exceeded for Client Id" } }, "type": "object" }, "CustomerIdentifierCollectionInput": { "description": "A collection of identifiers for customers in Mention Me.", "required": [ "identifiers" ], "properties": { "identifiers": { "description": "Maximum of 100 identifiers.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerIdentifierInterface" }, "maxItems": 100, "minItems": 1 } }, "type": "object" }, "CustomerPayloadCollectionOutput": { "description": "A collection of customers with their profile data.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPayload" }, "maxItems": 100, "minItems": 0 }, "errors": { "description": "All the identifiers which resulted in errors.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerErrorPayloadInterface" }, "maxItems": 100, "minItems": 0 } }, "type": "object" }, "RFC7807Problem": { "properties": { "status": { "type": "integer", "maximum": 599, "minimum": 200 }, "type": { "type": "string", "example": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "type": "object" }, "BulkCustomerResponse": { "description": "A collection of customer identifiers which were accepted, or resulted in an error.", "properties": { "accepted": { "description": "All the identifiers that were accepted.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerIdentifierInterface2" }, "maxItems": 100, "minItems": 0 }, "errors": { "description": "All the identifiers which resulted in errors.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerErrorPayloadInterface2" }, "maxItems": 100, "minItems": 0 } }, "type": "object" }, "CustomerEmailIdentifierInput": { "description": "A customer email address.", "required": [ "identifier" ], "properties": { "identifier": { "oneOf": [ { "$ref": "#/components/schemas/CustomerEmailIdentifier" } ] } }, "type": "object" }, "CustomerRewardsOutput": { "description": "An object representing the customer and the rewards they were given", "properties": { "data": { "$ref": "#/components/schemas/CustomerRewardsPayload" } }, "type": "object" }, "CustomerEmailIdentifierCollectionInput": { "description": "A collection of customer email addresses.", "required": [ "identifiers" ], "properties": { "identifiers": { "description": "Maximum of 100 identifiers.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerEmailIdentifier" }, "maxItems": 100, "minItems": 1 } }, "type": "object" }, "CustomerIdentifierInterface": { "discriminator": { "propertyName": "type", "mapping": { "email": "#/components/schemas/CustomerEmailIdentifier", "customerId": "#/components/schemas/CustomerIdIdentifier" } }, "oneOf": [ { "$ref": "#/components/schemas/CustomerEmailIdentifier" }, { "$ref": "#/components/schemas/CustomerIdIdentifier" } ] }, "CustomerPayload": { "description": "The profile of a customer.", "properties": { "customerId": { "title": "This will be the merchant's customer ID, which will be much more useful to them as consumers of the data", "description": "The ID of the customer generated by your system.", "type": "string", "maxLength": 255, "minLength": 1, "pattern": ".*.*?.*", "example": "CUST-1234" }, "email": { "type": "string", "maxLength": 320, "minLength": 1, "pattern": ".+\\@\\S+\\.\\S+", "example": "email@mention-me.com" }, "firstname": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\w", "example": "Jane" }, "surname": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\w", "example": "Doe" }, "phoneNumbers": { "type": "array", "items": { "type": "string" }, "example": [ "+447123456789", "+447987654321" ] }, "profileUrl": { "type": "string", "example": "https://mention-me.com/merchant/123/customers/43211234" }, "mentionMeCustomerId": { "description": "Mention Me's unique customer identifier", "type": "integer", "minimum": 1, "example": 987654321 }, "offers": { "$ref": "#/components/schemas/CollectionOfUserOfferPayloads" }, "nps": { "$ref": "#/components/schemas/CollectionOfNpsPayloads" }, "createdDate": { "title": "When this customer was first seen.", "type": "string", "format": "date-time" }, "lastPurchaseDate": { "title": "When was the most recent purchase date Mention Me have a record of.", "type": "string", "format": "date-time" }, "receivingEmails": { "title": "Is this customer willing to set to receive emails about the referral program?", "type": "boolean" }, "suspectedOfGaming": { "title": "Whether there has been suspicious activity and the customer is suspected of gaming to receive rewards.", "type": "boolean" }, "metrics": { "$ref": "#/components/schemas/MetricsPayload" }, "segments": { "$ref": "#/components/schemas/SegmentsPayload" } }, "type": "object" }, "CustomerErrorPayloadInterface": { "discriminator": { "propertyName": "reason", "mapping": { "notFound": "#/components/schemas/MissingCustomerErrorPayload" } }, "oneOf": [ { "$ref": "#/components/schemas/MissingCustomerErrorPayload" } ] }, "CustomerIdentifierInterface2": { "discriminator": { "propertyName": "type", "mapping": { "email": "#/components/schemas/CustomerEmailIdentifier2", "customerId": "#/components/schemas/CustomerIdIdentifier2" } }, "oneOf": [ { "$ref": "#/components/schemas/CustomerEmailIdentifier2" }, { "$ref": "#/components/schemas/CustomerIdIdentifier2" } ] }, "CustomerErrorPayloadInterface2": { "discriminator": { "propertyName": "reason", "mapping": { "notFound": "#/components/schemas/MissingCustomerErrorPayload2" } }, "oneOf": [ { "$ref": "#/components/schemas/MissingCustomerErrorPayload2" } ] }, "CustomerEmailIdentifier": { "required": [ "type" ], "properties": { "type": { "description": "The type of identifier.", "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "default": "", "maxLength": 320, "minLength": 1, "pattern": ".+\\@\\S+\\.\\S+" } }, "type": "object" }, "CustomerRewardsPayload": { "properties": { "customer": { "$ref": "#/components/schemas/CustomerEssentialsPayload" }, "rewards": { "type": "array", "items": { "$ref": "#/components/schemas/RewardablePayload" }, "maxItems": 100, "minItems": 0 } }, "type": "object" }, "CustomerIdIdentifier": { "required": [ "type", "value" ], "properties": { "type": { "description": "The type of identifier.", "type": "string", "enum": [ "customerId" ] }, "value": { "type": "string" } }, "type": "object" }, "CollectionOfUserOfferPayloads": { "description": "A collection of offers which a customer is enrolled to.\n\nAn offer is active until it either expires, or is archived by you.", "properties": { "active": { "type": "array", "items": { "$ref": "#/components/schemas/UserOfferPayload" } } }, "type": "object" }, "CollectionOfNpsPayloads": { "description": "A collection of NPS scores submitted by a customer.\n\nThe last 5 NPS scores submitted are shown as recent.", "properties": { "recent": { "type": "array", "items": { "$ref": "#/components/schemas/NpsPayload" } } }, "type": "object" }, "MetricsPayload": { "properties": { "successfulReferrals": { "type": "integer", "default": 0 }, "shareCount": { "$ref": "#/components/schemas/ShareCountPayload" }, "firstReferralDate": { "type": "string", "format": "date-time" }, "lastReferralDate": { "type": "string", "format": "date-time" }, "firstShareDate": { "type": "string", "format": "date-time" }, "lastShareDate": { "type": "string", "format": "date-time" } }, "type": "object" }, "SegmentsPayload": { "description": "Segments generated by Mention Me for a customer.\n\nThis includes segments to group customers based on their Extended Customer Revenue (ECR), and the referral network they belong to.", "properties": { "ecrStatus": { "type": "string", "example": "high" }, "ecrActivity": { "type": "string", "example": "lapsed" }, "networkId": { "type": "string", "example": "N-123" }, "predictedEcr": { "type": "string", "example": "high" } }, "type": "object" }, "MissingCustomerErrorPayload": { "properties": { "type": { "$ref": "#/components/schemas/CustomerIdentifierType" }, "value": { "type": "string" }, "reason": { "$ref": "#/components/schemas/CustomerIdentifierErrorReason" } }, "type": "object" }, "CustomerEmailIdentifier2": { "required": [ "type" ], "properties": { "type": { "description": "The type of identifier.", "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "default": "", "maxLength": 320, "minLength": 1, "pattern": ".+\\@\\S+\\.\\S+" } }, "type": "object" }, "CustomerIdIdentifier2": { "required": [ "type", "value" ], "properties": { "type": { "description": "The type of identifier.", "type": "string", "enum": [ "customerId" ] }, "value": { "type": "string" } }, "type": "object" }, "MissingCustomerErrorPayload2": { "properties": { "type": { "$ref": "#/components/schemas/CustomerIdentifierType" }, "value": { "type": "string" }, "reason": { "$ref": "#/components/schemas/CustomerIdentifierErrorReason" } }, "type": "object" }, "CustomerEssentialsPayload": { "description": "The profile of a customer", "properties": { "customerId": { "title": "This will be the merchant's customer ID, which will be much more useful to them as consumers of the data", "description": "The ID of the customer generated by your system.", "type": "string", "maxLength": 255, "minLength": 1, "pattern": ".*.*?.*", "example": "CUST-1234" }, "email": { "type": "string", "maxLength": 320, "minLength": 1, "pattern": ".+\\@\\S+\\.\\S+", "example": "email@mention-me.com" }, "firstname": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\w", "example": "Jane" }, "surname": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\w", "example": "Doe" }, "phoneNumbers": { "type": "array", "items": { "type": "string" }, "example": [ "+447123456789", "+447987654321" ] }, "profileUrl": { "type": "string", "example": "https://mention-me.com/merchant/123/customers/43211234" } }, "type": "object" }, "RewardablePayload": { "description": "A reward issued to a customer.", "properties": { "id": { "type": "integer" }, "fulfilledBy": { "title": "Returns how the reward was given to the customer.", "type": "string" }, "amount": { "title": "Return the amount if it's a float, otherwise null", "type": "number", "format": "float", "example": 100 }, "description": { "title": "Sometimes the amount of a reward is not a number so we don't want to return it as a float. Instead, we share the shortName, which is usually built on the description in the amount field.", "type": "string" }, "type": { "type": "string", "enum": [ "amount", "description", "number", "percent" ] }, "beforePurchase": { "title": "Only exposed if true, otherwise default is after purchase", "type": "boolean" }, "minimumFriendsRequired": { "type": "integer", "nullable": true }, "spendConstraint": { "description": "The minimum spend required to receive the reward.", "type": "number", "format": "float", "example": 50 }, "callToActionUrl": { "description": "The URL that the customer should be directed to after redeeming the reward. This is usually a link to an online store, or other means of using the reward.", "type": "string", "example": "https://www.your-website.com/new-customer-welcome" }, "couponCode": { "description": "If the issued reward is a coupon code, the code the customer should use to redeem the reward.", "type": "string", "example": "ABC-DEF-1234" }, "couponLink": { "description": "If the issued reward is a coupon link, the link the customer should use to redeem the reward.", "type": "string", "example": "https://www.your-website.com/redeem?code=ABC-DEF-1234" }, "securityCode": { "description": "An additional security code or PIN for using the reward.", "type": "string", "example": "12345" }, "expiryDate": { "description": "The date the reward expires.", "type": "string", "format": "date-time" } }, "type": "object" }, "UserOfferPayload": { "properties": { "id": { "type": "integer", "example": "1234" }, "description": { "type": "string", "example": "Referrer gets 20% off. Referee gets 20% off" }, "createdDate": { "type": "string", "format": "date-time" }, "expiryDate": { "type": "string", "format": "date-time" }, "situation": { "type": "string", "example": "postpurchase" }, "segment": { "type": "string", "example": "VIP" }, "shareLink": { "type": "string", "example": "https://your-brand.mention-me.com/m/ol/1234" }, "dashboardLink": { "type": "string", "example": "https://your-brand.mention-me.com/d/1234" } }, "type": "object" }, "NpsPayload": { "properties": { "answer": { "type": "integer", "maximum": 10, "minimum": 0, "example": "10" }, "feedback": { "title": "Note: this will only serialize the feedback for an {@see Webhooks::NPS_FEEDBACK} webhook type", "type": "string", "example": "Really great service!" }, "createdDate": { "type": "string", "format": "date-time" } }, "type": "object" }, "ShareCountPayload": { "properties": { "all": { "title": "This _will not_ always be equal to the sum of the share types we're exposing here, because we're **not** surfacing all of the possible share types available, we're only surfacing the most common ones.", "description": "The total number of successful shares made by the customer.", "type": "integer", "default": 0 }, "byFacebook": { "title": "Name Share Share Responses.", "description": "Total number of share responses recorded from Facebook.", "type": "integer", "default": 0 }, "byFacebookMessenger": { "title": "Name Share Share Responses.", "description": "Total number of share responses recorded from Facebook Messenger.", "type": "integer", "default": 0 }, "byName": { "title": "Name Share Share Responses.", "description": "Total number of successful shares made through sharing a referrers name at checkout.", "type": "integer", "default": 0 }, "byNativeShare": { "title": "Native Share Share Responses.", "description": "Total number of share responses recorded through the Native Share method. This is the number of successful shares which came from a share made through the native behaviour when sharing links on mobile devices.", "type": "integer", "default": 0 }, "byEmailLink": { "title": "Email Link Share Responses.", "description": "Total number of successful shares recorded from email links.", "type": "integer", "default": 0 }, "byWhatsApp": { "title": "WhatsApp Share Responses.", "description": "Total number of successful shares recorded from WhatsApp.", "type": "integer", "default": 0 } }, "type": "object" }, "CustomerIdentifierType": { "type": "string", "enum": [ "email", "customerId" ] }, "CustomerIdentifierErrorReason": { "type": "string", "enum": [ "notFound" ] } }, "securitySchemes": { "Bearer": { "type": "http", "description": "RFC8725 Compliant JWT", "bearerFormat": "JWT", "scheme": "bearer" } } }, "security": [ { "Bearer": [] } ], "tags": [ { "name": "Coupons" }, { "name": "Customers" }, { "name": "Referee" } ] }