# Memberships

Operations related to working with customers' membership details, i.e. linking loyalty program members to Mews customers and retrieving point values and tiers.

## List memberships by IDs

> Fetch the latest details of loyalty memberships from the provider's system using memberships' unique IDs.

```json
{"openapi":"3.1.1","info":{"title":"Mews Loyalty Reverse API","version":"2025.08.11"},"tags":[{"name":"Memberships","description":"Operations related to working with customers' membership details, i.e. linking loyalty program members to Mews customers and retrieving point values and tiers."}],"servers":[{"url":"[provider]","description":"Provider server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token provided by loyalty program provider."}},"parameters":{"acceptLanguage":{"name":"Accept-Language","in":"header","description":"Language preference for error messages and descriptions.\nIf not provided, English will be used as the default language.\n","schema":{"type":"string"}}},"schemas":{"listMembershipsRequest":{"type":"object","description":"Request payload for fetching the latest details of loyalty memberships using their unique provider IDs.","additionalProperties":false,"required":["mewsEnterpriseId","providerMembershipIds"],"properties":{"mewsEnterpriseId":{"$ref":"#/components/schemas/mewsEnterpriseId"},"providerEnterpriseId":{"$ref":"#/components/schemas/providerEnterpriseId"},"providerMembershipIds":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/providerMembershipId"},"description":"Array of membership IDs to retrieve."}}},"mewsEnterpriseId":{"title":"Mews Enterprise Identifier","type":"string","format":"uuid","description":"The identifier of the Mews enterprise on whose behalf the request has been made."},"providerEnterpriseId":{"title":"Provider Enterprise Identifier","type":"string","description":"An optional identifier of the enterprise from the loyalty provider on whose behalf the request has been made."},"providerMembershipId":{"type":"string","title":"Provider membership Identifier","description":"Unique internal identifier of membership from the loyalty provider. Can be the same as `membershipNumber` if no other value is needed.","maxLength":50},"listMembershipsResponse":{"type":"object","description":"Response payload containing an array of membership details for the requested provider membership IDs.","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","minItems":1,"maxItems":100,"description":"Array of matching memberships, if any membership is not found, return it with state `notFound`.","items":{"$ref":"#/components/schemas/membership"}}}},"membership":{"type":"object","description":"Contains membership information including provider membership ID, membership number, tier, points, and current status.","additionalProperties":false,"required":["providerMembershipId","membershipNumber","status"],"properties":{"providerMembershipId":{"$ref":"#/components/schemas/providerMembershipId"},"membershipNumber":{"$ref":"#/components/schemas/membershipNumber"},"tier":{"type":"string","maxLength":50},"points":{"type":"integer"},"status":{"type":"string","minLength":1,"enum":["pending","enrolled","canceled","declined","notFound"]},"expiresAt":{"type":"string","format":"date-time"},"deeplinkUrl":{"type":"string","format":"uri"}}},"membershipNumber":{"type":"string","title":"Membership number","description":"Member code or number, typically on loyalty card."},"problemDetail":{"type":"object","additionalProperties":true,"description":"A standardized format for problem details following [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).","title":"Problem details","required":["type","status","title","detail"],"properties":{"type":{"type":"string","minLength":1,"description":"A URI reference that identifies the problem type. Can be any URI or one of the predefined error types.","anyOf":[{"title":"Predefined Problem Types","type":"string","enum":["https://purl.mews.com/problem/core/not-found","https://purl.mews.com/problem/core/bad-request","https://purl.mews.com/problem/core/unprocessable-content","https://purl.mews.com/problem/core/unauthorized","https://purl.mews.com/problem/core/request-timeout","https://purl.mews.com/problem/core/too-many-requests","https://purl.mews.com/problem/core/internal-server-error","https://purl.mews.com/problem/loyalty/invalid-member-search-criteria"]},{"title":"Custom Problem Type URI","type":"string","format":"uri"}]},"title":{"type":"string","minLength":1,"maxLength":255,"description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem.","minimum":100,"maximum":599},"detail":{"type":"string","minLength":1,"description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","format":"uri","description":"A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced."},"errors":{"type":"array","description":"An array of field-level error details, typically used to describe validation failures or missing/invalid input fields.","items":{"type":"object","additionalProperties":false,"required":["type","pointer"],"properties":{"type":{"type":"string","minLength":1,"description":"A URI reference that identifies the field-level error type. Can be any URI or one of the predefined error types.","anyOf":[{"title":"Custom Field Error Type URI","type":"string","format":"uri"},{"title":"Predefined Field Error Types","type":"string","enum":["https://purl.mews.com/problem/core/field-required","https://purl.mews.com/problem/core/field-invalid-format","https://purl.mews.com/problem/core/field-too-short","https://purl.mews.com/problem/core/field-too-long","https://purl.mews.com/problem/core/field-out-of-range","https://purl.mews.com/problem/core/field-invalid-type","https://purl.mews.com/problem/core/field-not-allowed-value","https://purl.mews.com/problem/core/field-duplicate","https://purl.mews.com/problem/core/field-email-invalid"]}]},"pointer":{"type":"string","description":"JSON Pointer to the field that has an error. See [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) for the JSON Pointer specification.","minLength":1,"maxLength":255},"detail":{"type":"string","description":"A human-readable message describing the error.","maxLength":500}}}}}}},"responses":{"badRequest":{"description":"Bad Request - Returned when the request is invalid, such as missing required fields or containing data in an incorrect format.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/problemDetail"}}}},"unauthorized":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/problemDetail"}}}},"requestTimeout":{"description":"Request Timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/problemDetail"}}}},"internalServerError":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/problemDetail"}}}}}},"paths":{"/memberships/list":{"post":{"tags":["Memberships"],"summary":"List memberships by IDs","description":"Fetch the latest details of loyalty memberships from the provider's system using memberships' unique IDs.","operationId":"listMemberships","parameters":[{"$ref":"#/components/parameters/acceptLanguage"}],"requestBody":{"description":"Retrieves loyalty memberships matching the provided provider membership IDs.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/listMembershipsRequest"}}}},"responses":{"200":{"description":"List matching memberships.\n\nIf a membership with requested `providerMembershipId` is not found in the result set, it will be requested again later.\n\nMemberships with `status` of `notFound` will be removed on Mews' side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/listMembershipsResponse"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"408":{"$ref":"#/components/responses/requestTimeout"},"422":{"description":"Unprocessable Content - Used when the request is syntactically valid but fails due to business logic constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/problemDetail"}}}},"500":{"$ref":"#/components/responses/internalServerError"}}}}}}
```

## Link or unlink membership

> Links or unlinks a Mews customer to an existing membership in the loyalty program.

```json
{"openapi":"3.1.1","info":{"title":"Mews Loyalty Reverse API","version":"2025.08.11"},"tags":[{"name":"Memberships","description":"Operations related to working with customers' membership details, i.e. linking loyalty program members to Mews customers and retrieving point values and tiers."}],"servers":[{"url":"[provider]","description":"Provider server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token provided by loyalty program provider."}},"parameters":{"acceptLanguage":{"name":"Accept-Language","in":"header","description":"Language preference for error messages and descriptions.\nIf not provided, English will be used as the default language.\n","schema":{"type":"string"}}},"schemas":{"linkMembershipRequest":{"type":"object","description":"Request payload for linking or unlinking a Mews customer to an existing membership in the loyalty program.","additionalProperties":false,"required":["mewsEnterpriseId","providerMembershipId","mewsCustomerId","isLinked"],"properties":{"mewsEnterpriseId":{"$ref":"#/components/schemas/mewsEnterpriseId"},"providerMembershipId":{"allOf":[{"$ref":"#/components/schemas/providerMembershipId"}]},"providerEnterpriseId":{"$ref":"#/components/schemas/providerEnterpriseId"},"mewsCustomerId":{"$ref":"#/components/schemas/mewsCustomerId"},"isLinked":{"type":"boolean","description":"`true` if the customer is linked to the membership, `false` if unlinked.\n\nProviders may delete unlinked memberships; for purposes of this API it's not necessary to keep them stored on provider's side."}}},"mewsEnterpriseId":{"title":"Mews Enterprise Identifier","type":"string","format":"uuid","description":"The identifier of the Mews enterprise on whose behalf the request has been made."},"providerMembershipId":{"type":"string","title":"Provider membership Identifier","description":"Unique internal identifier of membership from the loyalty provider. Can be the same as `membershipNumber` if no other value is needed.","maxLength":50},"providerEnterpriseId":{"title":"Provider Enterprise Identifier","type":"string","description":"An optional identifier of the enterprise from the loyalty provider on whose behalf the request has been made."},"mewsCustomerId":{"type":"string","format":"uuid","title":"Mews customer Identifier","description":"Unique identifier of customer account in Mews. Can be used in Connector API."},"problemDetail":{"type":"object","additionalProperties":true,"description":"A standardized format for problem details following [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).","title":"Problem details","required":["type","status","title","detail"],"properties":{"type":{"type":"string","minLength":1,"description":"A URI reference that identifies the problem type. Can be any URI or one of the predefined error types.","anyOf":[{"title":"Predefined Problem Types","type":"string","enum":["https://purl.mews.com/problem/core/not-found","https://purl.mews.com/problem/core/bad-request","https://purl.mews.com/problem/core/unprocessable-content","https://purl.mews.com/problem/core/unauthorized","https://purl.mews.com/problem/core/request-timeout","https://purl.mews.com/problem/core/too-many-requests","https://purl.mews.com/problem/core/internal-server-error","https://purl.mews.com/problem/loyalty/invalid-member-search-criteria"]},{"title":"Custom Problem Type URI","type":"string","format":"uri"}]},"title":{"type":"string","minLength":1,"maxLength":255,"description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem.","minimum":100,"maximum":599},"detail":{"type":"string","minLength":1,"description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","format":"uri","description":"A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced."},"errors":{"type":"array","description":"An array of field-level error details, typically used to describe validation failures or missing/invalid input fields.","items":{"type":"object","additionalProperties":false,"required":["type","pointer"],"properties":{"type":{"type":"string","minLength":1,"description":"A URI reference that identifies the field-level error type. Can be any URI or one of the predefined error types.","anyOf":[{"title":"Custom Field Error Type URI","type":"string","format":"uri"},{"title":"Predefined Field Error Types","type":"string","enum":["https://purl.mews.com/problem/core/field-required","https://purl.mews.com/problem/core/field-invalid-format","https://purl.mews.com/problem/core/field-too-short","https://purl.mews.com/problem/core/field-too-long","https://purl.mews.com/problem/core/field-out-of-range","https://purl.mews.com/problem/core/field-invalid-type","https://purl.mews.com/problem/core/field-not-allowed-value","https://purl.mews.com/problem/core/field-duplicate","https://purl.mews.com/problem/core/field-email-invalid"]}]},"pointer":{"type":"string","description":"JSON Pointer to the field that has an error. See [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) for the JSON Pointer specification.","minLength":1,"maxLength":255},"detail":{"type":"string","description":"A human-readable message describing the error.","maxLength":500}}}}}}},"responses":{"badRequest":{"description":"Bad Request - Returned when the request is invalid, such as missing required fields or containing data in an incorrect format.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/problemDetail"}}}},"unauthorized":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/problemDetail"}}}},"requestTimeout":{"description":"Request Timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/problemDetail"}}}},"internalServerError":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/problemDetail"}}}}}},"paths":{"/memberships/link":{"put":{"tags":["Memberships"],"summary":"Link or unlink membership","description":"Links or unlinks a Mews customer to an existing membership in the loyalty program.","operationId":"updateMembershipLink","parameters":[{"$ref":"#/components/parameters/acceptLanguage"}],"requestBody":{"description":"Request payload containing the membership ID, customer ID, and link status.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/linkMembershipRequest"}}}},"responses":{"200":{"description":"Link operation was successful.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the link operation was successful."}}}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"408":{"$ref":"#/components/responses/requestTimeout"},"422":{"description":"Unprocessable Content - Used when the link operation is syntactically valid but fails due to business logic constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/problemDetail"}}}},"500":{"$ref":"#/components/responses/internalServerError"}}}}}}
```