--- updatedAt: 2026-05-26T22:53:01.000Z agentTools: projectIndex: https://developer.vinoshipper.com/llms.txt --- # Get a Customer by Email Address Get a single customer's details for specific email address # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Vinoshipper API Docs", "version": "3.0", "x-logo": { "url": "/static/img/brand/vinoshipper-logo.svg" } }, "servers": [ { "url": "https://vinoshipper.com" } ], "tags": [ { "name": "Customer", "description": "List and adjust customer's stored credit balance." }, { "name": "Customer", "description": "Generate Stripe-hosted payment collection links for a customer." }, { "name": "Customer", "description": "Search, create, and modify customer records" }, { "name": "Customer", "description": "Customer club memberships" } ], "paths": { "/api/v3/p/customers/exists": { "post": { "tags": [ "Customer" ], "summary": "Get a Customer by Email Address", "description": "Get a single customer's details for specific email address", "operationId": "exists", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerExistsForm" } } }, "required": true }, "responses": { "200": { "description": "Operation successful", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerDetails" } } } } }, "400": { "description": "Request has failed validation", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed" }, "403": { "description": "Insufficient permission", "content": {} }, "404": { "description": "Not Found" }, "500": { "description": "Internal server error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BasicAuth": [] } ] } } }, "components": { "schemas": { "Error": { "required": [ "code", "description" ], "type": "object", "properties": { "description": { "type": "string" }, "code": { "type": "string" }, "field": { "type": "string" }, "shortDescription": { "type": "string" } } }, "ErrorDetails": { "required": [ "status", "type" ], "type": "object", "properties": { "status": { "type": "integer", "format": "int32" }, "type": { "type": "string", "enum": [ "VALIDATION", "COMPLIANCE", "PAYMENT_FAILURE", "SERVER_ERROR", "ACCESS_DENIED", "CONFLICT" ] }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "ErrorResponse": { "required": [ "error" ], "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetails" } } }, "AccessPoint": { "required": [ "businessName", "city", "country", "lat", "lng", "locationId", "postalCode", "stateCode", "street1" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "locationId": { "type": "string", "description": "UPS Location ID" }, "lat": { "type": "number", "readOnly": true }, "lng": { "type": "number", "readOnly": true }, "imageUrl": { "type": "string", "description": "A full URL to an image associated with the Access Point", "nullable": true, "readOnly": true }, "hours": { "type": "string", "description": "Text describing open hours", "nullable": true, "readOnly": true }, "note": { "type": "string", "description": "Optional note from access point", "nullable": true, "readOnly": true }, "businessName": { "type": "string", "readOnly": true }, "street1": { "type": "string", "readOnly": true }, "street2": { "type": "string", "nullable": true, "readOnly": true }, "city": { "type": "string", "readOnly": true }, "postalCode": { "type": "string", "readOnly": true }, "stateCode": { "type": "string", "readOnly": true }, "country": { "type": "string", "description": "Two letter country code", "readOnly": true }, "phoneNumber": { "type": "string", "nullable": true, "readOnly": true } }, "description": "UPS access point", "nullable": true }, "Address": { "required": [ "city", "country", "fullName", "poBox", "postalCode", "stateCode", "street1", "suspectedPOBox", "verifiedNotPOBox" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "nullable": true, "readOnly": true }, "salutation": { "type": "string", "description": "Formal greeting or title of the customer" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "businessName": { "type": "string", "nullable": true }, "fullName": { "type": "string", "description": "Use firstName and lastName instead.", "nullable": true, "deprecated": true }, "street1": { "type": "string" }, "street2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "postalCode": { "type": "string", "description": "ZIP Code" }, "stateCode": { "type": "string" }, "country": { "type": "string", "description": "Two letter country code", "default": "US" }, "phoneNumber": { "type": "string", "description": "Use phone instead.", "nullable": true, "deprecated": true }, "phone": { "$ref": "#/components/schemas/InternationalPhoneNumber" }, "accessPoint": { "$ref": "#/components/schemas/AccessPoint" }, "description": { "type": "string", "description": "A description for the address, e.g. Home, Work", "nullable": true }, "suspectedPOBox": { "type": "boolean", "description": "True if the address is suspected of being a PO Box", "readOnly": true }, "poBox": { "type": "boolean", "description": "True if this address is confirmed as a PO Box", "readOnly": true }, "verifiedNotPOBox": { "type": "boolean", "description": "True if someone has confirmed this address is not a PO Box. Club processing skips its PO Box check for such an address even when the text still reads like one.", "readOnly": true }, "linkedAddress": { "$ref": "#/components/schemas/LinkedAddress" } }, "description": "The address of the location where the sale is made", "nullable": true }, "CustomerTagView": { "required": [ "color", "customerCount", "discountUsageCount", "feeUsageCount", "id", "name", "retired", "sortOrder" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the tag", "format": "int64" }, "name": { "type": "string", "description": "Name of the tag", "example": "VIP Customer" }, "color": { "type": "string", "description": "User theme color (e.g., 'indigo', 'cyan-light')", "example": "indigo" }, "description": { "type": "string", "description": "Optional description of the tag" }, "sortOrder": { "type": "integer", "description": "Sort order for display", "format": "int32" }, "retired": { "type": "boolean", "description": "Whether the tag is retired" }, "customerCount": { "type": "integer", "description": "Number of customers assigned to this tag", "format": "int32" }, "discountUsageCount": { "type": "integer", "description": "Number of discounts (any state) using this tag as criteria", "format": "int32" }, "feeUsageCount": { "type": "integer", "description": "Number of fees (any state) using this tag as criteria", "format": "int32" } }, "description": "Customer tag for segmentation and categorization" }, "InternationalPhoneNumber": { "type": "object", "properties": { "number": { "type": "string" }, "country": { "type": "integer", "format": "int32" }, "extension": { "type": "string" } }, "nullable": true }, "LinkedAddress": { "required": [ "city", "country", "fullName", "postalCode", "stateCode", "street1" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "nullable": true, "readOnly": true }, "salutation": { "type": "string", "description": "Formal greeting or title of the customer" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "businessName": { "type": "string", "nullable": true }, "fullName": { "type": "string", "description": "Use firstName and lastName instead.", "nullable": true, "deprecated": true }, "street1": { "type": "string" }, "street2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "postalCode": { "type": "string", "description": "ZIP Code" }, "stateCode": { "type": "string" }, "country": { "type": "string", "description": "Two letter country code", "default": "US" }, "phoneNumber": { "type": "string", "description": "Use phone instead.", "nullable": true, "deprecated": true }, "phone": { "$ref": "#/components/schemas/InternationalPhoneNumber" }, "description": { "type": "string", "description": "A description for the address, e.g. Home, Work", "nullable": true }, "accessPoint": { "$ref": "#/components/schemas/AccessPoint" } } }, "DateOfBirth": { "required": [ "day", "month", "year" ], "type": "object", "properties": { "day": { "type": "integer", "format": "int32" }, "month": { "type": "integer", "format": "int32" }, "year": { "type": "integer", "format": "int32" } } }, "CustomerNote": { "required": [ "dateCreated", "dateModified", "id", "isAlert", "isMarkdown", "isPinned", "readOnly", "text", "type" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "text": { "type": "string" }, "author": { "type": "string" }, "readOnly": { "type": "boolean" }, "dateCreated": { "type": "string", "format": "date-time" }, "dateModified": { "type": "string", "format": "date-time" }, "type": { "type": "string" }, "isAlert": { "type": "boolean" }, "isPinned": { "type": "boolean" }, "isMarkdown": { "type": "boolean" } } }, "ClubMembershipGift": { "type": "object", "properties": { "id": { "type": "integer", "description": "Membership Gift ID", "format": "int32" }, "salutation": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phone": { "$ref": "#/components/schemas/InternationalPhoneNumber" }, "email": { "type": "string", "description": "Gift recipient's email address" }, "dateOfBirth": { "$ref": "#/components/schemas/DateOfBirth" } }, "description": "Optional gift details for this membership", "nullable": true }, "ClubMembershipSummary": { "required": [ "clubId", "clubName", "dateJoined", "description", "hold", "pickup", "skipLimit", "title" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Membership ID", "format": "int32" }, "clubId": { "type": "integer", "format": "int32" }, "clubName": { "type": "string" }, "dateJoined": { "type": "string", "format": "date" }, "shippingAddress": { "$ref": "#/components/schemas/Address" }, "pickup": { "type": "boolean", "description": "True if the member picks up their order, false if it is shipped." }, "gift": { "$ref": "#/components/schemas/ClubMembershipGift" }, "releasesRemaining": { "type": "integer", "description": "Club releases remaining before the membership is automatically expired. This is null when the membership does not expire.", "format": "int32", "nullable": true }, "hold": { "type": "boolean", "description": "True if the membership is currently on hold" }, "holdStartDate": { "type": "string", "description": "Null unless the membership will be on hold starting on the given date", "format": "date", "nullable": true }, "holdEndDate": { "type": "string", "description": "Null unless the membership will be on hold until the given date", "format": "date", "nullable": true }, "holdReason": { "type": "string" }, "skipLimit": { "$ref": "#/components/schemas/SkipLimitDetails" }, "profileUpdateToken": { "type": "string", "description": "The current membership profile update token if one has been generated and not expired", "nullable": true }, "shippingClass": { "$ref": "#/components/schemas/ShippingClass" }, "memberEnrolledById": { "type": "integer", "description": "The team member ID of the person that enrolled this club membership. This is null if the team member is unassigned.", "format": "int32", "nullable": true }, "memberEnrolledByName": { "type": "string" }, "memberDeactivatedById": { "type": "integer", "description": "The team member ID of the person that deactivated this club membership. This is null if the team member is unassigned.", "format": "int32", "nullable": true }, "title": { "type": "string" }, "description": { "type": "string" } } }, "ShippingClass": { "required": [ "code" ], "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" } }, "description": "Customer's preferred shipping class" }, "SkipLimitDetails": { "required": [ "canSkip", "ignoreSkipLimit", "releasesSkipped", "skipLimitEnabled", "skipLimitOverridden", "skipsRemaining" ], "type": "object", "properties": { "skipLimitEnabled": { "type": "boolean", "description": "True if release skip limit is enabled for the club" }, "releasesSkipped": { "type": "integer", "description": "The number of releases skipped for this membership", "format": "int32" }, "ignoreSkipLimit": { "type": "boolean", "description": "True if this membership ignores the club's skip limit" }, "skipLimitOverridden": { "type": "boolean", "description": "Skips remaining overrides the club skip limit" }, "skipsRemaining": { "type": "integer", "description": "The number of orders the membership can skip (can be negative)", "format": "int32" }, "canSkip": { "type": "boolean", "description": "Can the member skip the next order" } }, "description": "Details related to release skip limits" }, "AlternatePhoneNumber": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "number": { "type": "string" }, "label": { "type": "string" }, "isMobile": { "type": "boolean" }, "mobile": { "type": "boolean", "writeOnly": true } } }, "ClubDetails": { "required": [ "archived", "giftEnabled", "id", "name", "pickupEnabled", "pickupOnly", "pickupRequiresAddress", "preorder", "private", "producerId", "producerName", "skipLimit", "skipLimitEnabled" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "description": { "type": "string" }, "producerName": { "type": "string", "description": "The name of the producer that owns this club" }, "producerId": { "type": "integer", "description": "The ID of the producer that owns this club", "format": "int32" }, "pickupEnabled": { "type": "boolean" }, "pickupRequiresAddress": { "type": "boolean" }, "pickupOnly": { "type": "boolean" }, "giftEnabled": { "type": "boolean" }, "giftReleaseOptions": { "type": "array", "description": "A list of valid buyer gift release options for a club. A null value indicated no expiration is an option.", "items": { "type": "integer", "description": "A list of valid buyer gift release options for a club. A null value indicated no expiration is an option.", "format": "int32" } }, "private": { "type": "boolean" }, "archived": { "type": "boolean" }, "preorder": { "type": "boolean", "description": "True if the club is for pre-orders" }, "skipLimitEnabled": { "type": "boolean", "description": "True if skip limit is enabled for this club" }, "skipLimit": { "type": "integer", "description": "The maximum number of releases a membership can skip", "format": "int32" }, "skipMinimumOrderValue": { "type": "number", "description": "A release counts as skipped if the order value is below this amount. Null means not configured", "nullable": true }, "skipMinimumOrderQuantity": { "type": "integer", "description": "A release counts as skipped if the order quantity is below this amount. Null means not configured", "format": "int32", "nullable": true } } }, "ClubMembershipDetails": { "required": [ "club", "clubId", "clubName", "dateJoined", "description", "hold", "pickup", "skipLimit", "title" ], "type": "object", "properties": { "membershipSummary": { "$ref": "#/components/schemas/ClubMembershipSummary" }, "club": { "$ref": "#/components/schemas/ClubDetails" }, "producer": { "$ref": "#/components/schemas/ProducerDetails" }, "memberEnrolledByName": { "type": "string" }, "profileUpdateToken": { "type": "string", "description": "The current membership profile update token if one has been generated and not expired", "nullable": true }, "title": { "type": "string" }, "shippingClass": { "$ref": "#/components/schemas/ShippingClass" }, "hold": { "type": "boolean", "description": "True if the membership is currently on hold" }, "memberEnrolledById": { "type": "integer", "description": "The team member ID of the person that enrolled this club membership. This is null if the team member is unassigned.", "format": "int32", "nullable": true }, "memberDeactivatedById": { "type": "integer", "description": "The team member ID of the person that deactivated this club membership. This is null if the team member is unassigned.", "format": "int32", "nullable": true }, "description": { "type": "string" }, "id": { "type": "integer", "description": "Membership ID", "format": "int32" }, "shippingAddress": { "$ref": "#/components/schemas/Address" }, "clubName": { "type": "string", "description": "The club's name. Please use club.name", "deprecated": true }, "releasesRemaining": { "type": "integer", "description": "Club releases remaining before the membership is automatically expired. This is null when the membership does not expire.", "format": "int32", "nullable": true }, "gift": { "$ref": "#/components/schemas/ClubMembershipGift" }, "dateJoined": { "type": "string", "format": "date" }, "holdStartDate": { "type": "string", "description": "Null unless the membership will be on hold starting on the given date", "format": "date", "nullable": true }, "holdEndDate": { "type": "string", "description": "Null unless the membership will be on hold until the given date", "format": "date", "nullable": true }, "holdReason": { "type": "string" }, "skipLimit": { "$ref": "#/components/schemas/SkipLimitDetails" }, "pickup": { "type": "boolean", "description": "True if the member picks up their order, false if it is shipped." }, "clubId": { "type": "integer", "description": "The club's id. Please use club.id", "format": "int32", "deprecated": true } } }, "ProducerDetails": { "required": [ "id", "name", "type" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "PRODUCER", "RETAILER", "IMPORTER", "WHOLESALER", "BRAND_OWNER", "BREWER", "DISTILLERY", "AFFINITY_PROGRAM" ] }, "imageUrl": { "type": "string" }, "website": { "type": "string" }, "searchKey": { "type": "string" } } }, "CreditCardSummary": { "required": [ "expired", "expiresMonth", "expiresYear", "isDefaultCard", "lastFourDigits", "type" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "type": { "type": "string", "enum": [ "VISA", "MASTERCARD", "AMEX", "EN_ROUTE", "DINERS_CLUB", "DISCOVER", "JCB", "CARTE_BLANCHE" ] }, "cardHolderName": { "type": "string" }, "lastFourDigits": { "type": "string" }, "expiresMonth": { "type": "string" }, "expiresYear": { "type": "string" }, "expired": { "type": "boolean" }, "billingPostalCode": { "type": "string" }, "isDefaultCard": { "type": "boolean" } } }, "CustomerExistsForm": { "type": "object", "properties": { "email": { "type": "string" } } }, "AlternateInternationalPhoneNumber": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "number": { "$ref": "#/components/schemas/InternationalPhoneNumber" }, "label": { "type": "string" }, "isMobile": { "type": "boolean" }, "mobile": { "type": "boolean", "writeOnly": true } } }, "CustomerDetails": { "required": [ "ageVerified", "clubMember", "clubsOnHold", "email", "hasOpenPickups", "hasOrderHistory", "id", "issues", "lifeTimeOrders", "lifeTimeValue", "optedIntoMarketingEmails", "optedIntoMarketingSms", "storedCredit", "unsubscribedFromMarketingEmails", "wholesale" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "wholesale": { "type": "boolean" }, "wholesaleType": { "type": "string", "description": "The wholesale customer type (only set for wholesale customers)", "nullable": true, "enum": [ "DISTRIBUTOR", "RETAILER", "RESTAURANT", "OTHER" ] }, "defaultInvoiceTerms": { "type": "string", "description": "Default payment terms for wholesale invoices (only set for wholesale customers)", "nullable": true, "enum": [ "DUE_ON_RECEIPT", "NET_15", "NET_30" ] }, "salutation": { "type": "string", "nullable": true }, "company": { "type": "string" }, "email": { "type": "string" }, "dateOfBirth": { "$ref": "#/components/schemas/DateOfBirth" }, "primaryPhone": { "$ref": "#/components/schemas/InternationalPhoneNumber" }, "otherPhones": { "type": "array", "items": { "$ref": "#/components/schemas/AlternateInternationalPhoneNumber" } }, "primaryPhoneNumber": { "$ref": "#/components/schemas/AlternatePhoneNumber" }, "otherPhoneNumbers": { "type": "array", "description": "Deprecated, use otherPhones", "items": { "$ref": "#/components/schemas/AlternatePhoneNumber" } }, "memberNumber": { "type": "string", "description": "The producer's identifier for this customer" }, "enrolledById": { "type": "integer", "description": "The team member ID of the person that enrolled this customer", "format": "int32" }, "enrolledBy": { "type": "string", "description": "The team member name of the person that enrolled this customer" }, "customerSince": { "type": "string", "description": "Represents the date when the customer profile was created", "format": "date" }, "optedIntoMarketingEmails": { "type": "boolean", "description": "Customer's email marketing preference. May not reflect opt-outs managed by the email provider." }, "unsubscribedFromMarketingEmails": { "type": "boolean", "description": "True if the customer explicitly unsubscribed from email marketing. When set, the producer cannot re-enable email marketing (only the customer can re-consent), mirroring the SMS opt-in rule." }, "optedIntoMarketingSms": { "type": "boolean", "description": "Customer's SMS marketing preference. May not reflect opt-outs managed by the SMS provider." }, "shippingAddress": { "$ref": "#/components/schemas/Address" }, "mailingAddress": { "$ref": "#/components/schemas/Address" }, "otherAddresses": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "clubMember": { "type": "boolean" }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/ClubMembershipDetails" } }, "numOfWineclubOrders": { "type": "integer", "format": "int32", "writeOnly": true }, "creditCard": { "$ref": "#/components/schemas/CreditCardSummary" }, "storedCredit": { "type": "number", "description": "The amount of stored credit available for this customer" }, "lifeTimeOrders": { "type": "integer", "description": "The count of orders purchased by this customer", "format": "int32" }, "lifeTimeValue": { "type": "number", "description": "The total value of orders purchased by this customer" }, "totalInvoicesDue": { "type": "number", "description": "The total value of unpaid invoices (wholesale customers only)", "nullable": true }, "hasOpenPickups": { "type": "boolean", "description": "Does the customer have any pickup orders ready to be picked up?" }, "history": { "type": "array", "description": "Deprecated: Use customer notes endpoint instead", "deprecated": true, "items": { "$ref": "#/components/schemas/CustomerNote" } }, "alerts": { "type": "array", "description": "List of data problems to notify producers to fix", "deprecated": true, "items": { "type": "string", "description": "List of data problems to notify producers to fix", "deprecated": true } }, "issues": { "$ref": "#/components/schemas/Issue" }, "profileImageUrl": { "type": "string" }, "ageVerified": { "type": "boolean" }, "customerTags": { "type": "array", "description": "The customer tags assigned to this customer", "items": { "$ref": "#/components/schemas/CustomerTagView" } }, "mostRecentNote": { "$ref": "#/components/schemas/CustomerNote" }, "clubsOnHold": { "type": "boolean", "description": "True if all club memberships are on hold" }, "hasOrderHistory": { "type": "boolean", "description": "Has this customer ever made an order or have any upcoming club releases?" }, "fullName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } }, "Issue": { "type": "object", "properties": { "card": { "type": "array", "description": "The list of alerts for card errors", "items": { "type": "string", "description": "The list of alerts for card errors" } }, "order": { "type": "array", "description": "The list of alerts for order problem", "items": { "type": "string", "description": "The list of alerts for order problem" } } }, "description": "Data problems to alert producers to fix" } }, "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic" } } } } ```