# 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"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mews.com/loyalty-partner/api-operations/memberships.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.