Memberful API
Memberful's API uses GraphQL, a flexible and powerful data query language. To learn more, see the the official GraphQL documentation.
In this help doc:
- Using the GraphQL API Explorer
- Endpoint
- Authentication
- Error handling
- Queries and Mutations
- Pagination
- Member metadata
Using the GraphQL API Explorer
The GraphQL API Explorer serves as live, always up to date documentation. It also allows you to construct and test your queries and mutations.
Once you generate an API key, you can access it by clicking on the Open API Explorer link in custom applications list or custom application details page:
Important: The GraphQL API Explorer makes use of your real, production data.
Endpoint
The Memberful GraphQL API has a single endpoint:
https://YOURSITE.memberful.com/api/graphql
This endpoint always remains constant for all operations. All requests sent to the endpoint should be POST requests. The payload must contain a string called query
with your query or mutation. If there are no errors, the endpoint will always return a JSON response.
Authentication
Each API request needs to include authorization header:
Authorization: Bearer <your-api-key>
To generate API keys, create a new Custom Application (Settings → Integrate → Custom Apps) from your Memberful dashboard.
Error handling
The GraphQL endpoint should always respond with a HTTP 200
status code. If there is a problem processing your request, the response payload will include details about the error.
Authentication error:
{ "errors": [ { "message": "Invalid authentication token." } ] }
Invalid request error:
{ "errors": [ { "message": "Field 'memberCreate' is missing required arguments: email, fullName", "locations": [ { "line": 2, "column": 3 } ], "fields": [ "mutation", "createMember" ] } ] }
Queries and Mutations
GraphQL supports both queries and mutations. We allow up to 100 queries per minute to pull your data from Memberful and mutations to modify your Memberful data.
Example query:
query { member(id: 1) { id fullName email subscriptions { id plan { id name } } } }
Response:
{ "data": { "member": { "id": "1", "fullName": "John Doe", "email": "john.doe@example.com", "subscriptions": [ { "id": "1", "plan": { "id": "1", "name": "Monthly" } } ] } } }
Example mutation:
mutation { memberCreate(email:"john.doe@example.com", fullName:"John Doe") { member { id username } } }
Response:
{ "data": { "memberCreate": { "member": { "id": "1", "username": "john588361" } } } }
Read more about queries and mutations.
Pagination
You'll use GraphQL connection types to detect paginated data.
Example query:
query { members(first: 2, after: "MTA=") { totalCount pageInfo { startCursor endCursor hasNextPage hasPreviousPage } edges { node { id email } } } }
Example response:
{ "data": { "members": { "totalCount": 100, "pageInfo": { "startCursor": "MTE=", "endCursor": "MjA=", "hasNextPage": true, "hasPreviousPage": true }, "edges": [ { "node": { "id": "11", "email": "email11@example.com" } }, { "node": { "id": "12", "email": "email12@example.com" } } ] } } }
Read more about GraphQL pagination.
Member metadata
The Memberful GraphQL API also supports storing custom metadata on each member. This data is not accessible elsewhere on the site, only via the API.
All metadata is set through a JSON object and limited to string values. A maximum of 50 keys can be stored on each member, with key lengths up to 40 characters and values up to 500 characters long.
Example mutation:
mutation { memberUpdate(id: 1, metadata: "{\"company\": \"Acme Corporation\"}") { member { id metadata } } }
All metadata is additive, meaning if you don't add a specific key/value pair on a future update it will not delete that original value. You must explicitly delete a key by setting its value to an empty string.
Can't find what you're looking for? We'd love to help! 💪
Send us a message through the orange chat bubble in the lower right corner of the page. You'll hear back within a few hours Monday - Friday. 😀