Memberships API
Memberships
A Memberships record represents a customer's enrollment in a membership program. Each customer can have multiple memberships, but only one membership per membership program.
The membership object
Attributes
id integer
Unique numeric identifier for the Membership.
address_id integer
Unique numeric identifier for the address for the Subscription associated with the Membership.
customer_id integrer
Unique numeric identifier for the Customer associated with the Membership.
membership_program_id integer
Unique numeric identifier for the Membership Program associated with the Membership.
purchase_item_id integer
Unique numeric identifier for the Subscription associated with the Membership.
cancellation_reason string
Reason provided for cancellation.
cancellation_reason_comments string
Additional comment for cancellation. Maximum length is 1024 characters.
cancelled_at datetime
The date and time the Membership was cancelled.
charge_interval_frequency string
The number of units (specified in charge_interval_unit) between each Charge for the Subscription associated with the Membership. For example, charge_interval_unit=month and charge_interval_frequency=3, indicate charge every 3 months.
charge_interval_unit string
The frequency unit determines when the Order is created for the Subscription associated with the Membership.
Possible values: day, week, month
created_at datetime
The date and time when the Membership was created.
deleted_at datetime
The date and time when the Membership was deleted.
expires_at datetime
The date and time when the Membership expires.
external_product_id integer
Unique numeric identifier of the product id linked to the Subscription associated with the Membership as it appears in external platforms.
external_variant_id integer
Unique numeric identifier of the variant id linked to the Subscription associated with the Membership as it appears in external platforms.
has_queued_charges boolean
Retrieves true if there is a queued Charge for the Subscription associated with the Membership. Otherwise, retrieves false.
next_charge_scheduled_at datetime
Date of the next Charge for the Subscription associated with the Membership.
presentment_currency string
The presentment currency of theSubscription associated with the Membership.
Related guides: Supported currencies
price string
The price of the item before discounts, taxes, or shipping have been applied.
product_title string
The name of the product linked to the Subscription associated with the Membership as it appears in external platforms.
purchase_item_status string
The status of the Subscription associated with the Membership.
purchase_item_type string
The type of Subscription associated with the Membership.
Possible values: membership_subscription
quantity string
The number of items in the Subscription associated with the Membership.
status string
The status of the Membership.
Possible values: active, inactive
type string
The Membership type.
Possible values: membership_subscription, manual
updated_at datetime
The date and time when the Membership was last updated.
variant_title string
The name of the variant linked to the Subscription associated with the Membership as it appears in external platforms.
Retrieve a membership
Retrieves membership for customer based on specified membership id.
Scopes: read_memberships
Request
curl --location --request GET 'https://api.rechargeapps.com/memberships/{id}' \
--header 'X-Recharge-Version: 2021-11' \
--header 'Content-Type: application/json' \
--header 'X-Recharge-Access-Token: {api_key}'
Responses
{
"membership": {
"id": 2175,
"address_id": 107663460,
"customer_id": 97834350,
"membership_program_id": 55,
"purchase_item_id": 296762182,
"cancellation_reason": null,
"cancellation_reason_comments": null,
"cancelled_at": null,
"charge_interval_frequency": "1",
"charge_interval_unit": "month",
"created_at": "2022-11-04T02:37:45+00:00",
"deleted_at": null,
"expires_at": "2023-02-20T12:00:00+00:00",
"external_product_id": 7014208569481,
"external_variant_id": 40754487132297,
"has_queued_charges": true,
"next_charge_scheduled_at": "2023-02-20T00:00:00",
"presentment_currency": "USD",
"price": 79.0,
"product_title": "Happy Socks VIP",
"purchase_item_status": "active",
"purchase_item_type": "membership_subscription",
"quantity": 1,
"status": "active",
"type": "membership_subscription",
"updated_at": "2023-01-20T15:28:29+00:00",
"variant_title": ""
}
}
{
"errors": "Not Found"
}
List memberships
Returns all memberships from the store, or memberships for the user given in the parameter.
Scopes: read_memberships
Query Parameters
created_at_min string
Returns memberships created after a given date and time.
created_at_max string
Returns memberships created before a given date and time.
customer_email string
Returns the memberships linked to the email address provided.
customer_id string
Return the memberships linked to the given Recharge customer id.
expires_at_min string
Returns memberships that expire after a given date and time.
expires_at_max string
Returns memberships that expire before a given date and time.
ids string
Comma-separated list of membership_ids to filter
include_deleted string
Returns all deleted memberships.
Possible values: true, false
include_cancelled string
Returns all memberships with a cancelled membership subscription.
Possible values: true, false
membership_program_ids string
Returns the memberships linked to a given membership_program_id.
program_type string
Returns memberships that have the provided type.
Possible values: paid_recurring, subscriber
status string
Returns memberships that have the provided status.
Possible values: active, inactive
type string
Returns memberships that have the provided type.
Possible values: membership_subscription, manual
updated_at_min string
Returns memberships updated after a given date and time.
updated_at_max string
Returns memberships updated before a given date and time.
Request
curl --location --request GET 'https://api.rechargeapps.com/memberships' \
--header 'X-Recharge-Version: 2021-11' \
--header 'Content-Type: application/json' \
--header 'X-Recharge-Access-Token: {api_key}'
Response
{
"next_cursor": null,
"previous_cursor": null,
"memberships": [
{
"id": 2175,
"address_id": 107663460,
"customer_id": 97834350,
"membership_program_id": 55,
"purchase_item_id": 296762182,
"cancellation_reason": null,
"cancellation_reason_comments": null,
"cancelled_at": null,
"charge_interval_frequency": "1",
"charge_interval_unit": "month",
"created_at": "2022-11-04T02:37:45+00:00",
"deleted_at": null,
"expires_at": "2023-02-20T12:00:00+00:00",
"external_product_id": 7014208569481,
"external_variant_id": 40754487132297,
"has_queued_charges": true,
"next_charge_scheduled_at": "2023-02-20T00:00:00",
"presentment_currency": "USD",
"price": 79.0,
"product_title": "Happy Socks VIP",
"purchase_item_status": "active",
"purchase_item_type": "membership_subscription",
"quantity": 1,
"status": "active",
"type": "membership_subscription",
"updated_at": "2023-01-20T15:28:29+00:00",
"variant_title": ""
},
{
"id": 381,
"address_id": 103274284,
"customer_id": 94496106,
"membership_program_id": 55,
"purchase_item_id": 279961401,
"cancellation_reason": "This membership is too expensive",
"cancellation_reason_comments": null,
"cancelled_at": "2023-01-20T15:31:46+00:00",
"charge_interval_frequency": "1",
"charge_interval_unit": "month",
"created_at": "2022-09-09T23:00:11+00:00",
"deleted_at": null,
"expires_at": "2023-01-20T15:31:46+00:00",
"external_product_id": 7014208569481,
"external_variant_id": 40754487132297,
"has_queued_charges": false,
"next_charge_scheduled_at": null,
"presentment_currency": "USD",
"price": 79.0,
"product_title": "Happy Socks VIP",
"purchase_item_status": "cancelled",
"purchase_item_type": "membership_subscription",
"quantity": 1,
"status": "inactive",
"type": "membership_subscription",
"updated_at": "2023-01-20T15:31:45+00:00",
"variant_title": ""
},
{
"id": 380,
"address_id": 103273919,
"customer_id": 94495787,
"membership_program_id": 55,
"purchase_item_id": 279959958,
"cancellation_reason": null,
"cancellation_reason_comments": null,
"cancelled_at": null,
"charge_interval_frequency": "1",
"charge_interval_unit": "month",
"created_at": "2022-09-09T22:53:54+00:00",
"deleted_at": null,
"expires_at": "2023-02-20T12:00:00+00:00",
"external_product_id": 7014208569481,
"external_variant_id": 40754487132297,
"has_queued_charges": true,
"next_charge_scheduled_at": "2023-02-20T00:00:00",
"presentment_currency": "USD",
"price": 79.0,
"product_title": "Happy Socks VIP",
"purchase_item_status": "active",
"purchase_item_type": "membership_subscription",
"quantity": 1,
"status": "active",
"type": "membership_subscription",
"updated_at": "2023-01-20T15:31:07+00:00",
"variant_title": ""
}
]
}
Cancel a membership
Cancel a customer's membership.
Scopes: write_memberships
Body Parameters
cancel_immediately string
Cancels a customer's membership immediately.
Possible values: true, false
Note
Manual memberships can only be cancelled immediately.
cancellation_reason string
Membership subscription cancellation reason.
cancellation_reason_comments string
Membership subscription cancellation reason comments.
Request
curl --location --request POST 'https://api.rechargeapps.com/memberships/{id}/cancel' \
--header 'X-Recharge-Version: 2021-11' \
--header 'Content-Type: application/json' \
--header 'X-Recharge-Access-Token: {api_token}' \
--data-raw '{
"cancel_immediately": "false",
"cancellation_reason": "reason",
"cancellation_reason_comment": "akjnfkjbf"
}'
Response
{
"membership": {
"id": 18811,
"address_id": 124811284,
"customer_id": 113497486,
"membership_program_id": 281,
"purchase_item_id": 368643039,
"cancellation_reason": "This was too expensive",
"cancellation_reason_comments": null,
"cancelled_at": "2023-08-17T17:25:29+00:00",
"charge_interval_frequency": "12",
"charge_interval_unit": "month",
"created_at": "2023-05-25T18:33:07+00:00",
"deleted_at": null,
"expires_at": "2024-06-01T12:00:00+00:00",
"external_product_id": 7167971065993,
"external_variant_id": 41177746964617,
"has_queued_charges": false,
"next_charge_scheduled_at": null,
"presentment_currency": "USD",
"price": 100.0,
"product_title": "Happy Socks VIP (Annual membership)",
"purchase_item_status": "cancelled",
"purchase_item_type": "membership_subscription",
"quantity": 1,
"status": "active",
"type": "membership_subscription",
"updated_at": "2023-08-17T17:25:29+00:00",
"variant_title": "Default Title"
}
}
{
"error": "Not Found"
}
{
"errors": {
"status": [
"Membership is already inactive."
]
}
}
{
"errors": {
"status": [
"Membership without an associated membership can only be cancelled immediately."
]
}
}
Activate a membership
Activates a customer's cancelled membership.
Scopes: write_memberships
Parameters
expires_at datetime
The new expiration date for the membership.
Note
Only supported for manual memberships.
Request
curl --location --request POST 'https://api.rechargeapps.com/memberships/{id}/activate' \
--header 'X-Recharge-Version: 2021-11' \
--header 'Content-Type: application/json' \
--header 'X-Recharge-Access-Token: {api token}' \
--data-raw '{
"expires_at": ""
}'
Response
{
"membership": {
"id": 18811,
"address_id": 124811284,
"customer_id": 113497486,
"membership_program_id": 281,
"purchase_item_id": 368643039,
"cancellation_reason": null,
"cancellation_reason_comments": null,
"cancelled_at": null,
"charge_interval_frequency": "12",
"charge_interval_unit": "month",
"created_at": "2023-05-25T18:33:07+00:00",
"deleted_at": null,
"expires_at": "2024-06-01T12:00:00+00:00",
"external_product_id": 7167971065993,
"external_variant_id": 41177746964617,
"has_queued_charges": true,
"next_charge_scheduled_at": "2024-06-01T00:00:00",
"presentment_currency": "USD",
"price": 100.0,
"product_title": "Happy Socks VIP (Annual membership)",
"purchase_item_status": "active",
"purchase_item_type": "membership_subscription",
"quantity": 1,
"status": "active",
"type": "membership_subscription",
"updated_at": "2023-08-17T17:26:44+00:00",
"variant_title": "Default Title"
}
}
{
"error": "Not Found"
}
{
"errors": {
"membership": [
"Membership is already active"
]
}
}
Change a membership
Changes the membership program and/or membership product on a customer's membership.
Scopes: write_memberships
Parameters
membership_program_id integer
Unique numeric identifier for the Membership Program associated with the Membership.
charge_interval_frequency string
The number of units (specified in charge_interval_unit) between each Charge. For example, charge_interval_unit=month and charge_interval_frequency=3, indicate charge every 3 months.
charge_interval_unit string
The frequency unit used to determine when a subscription’s order is created.
Possible values: day, week, month
external_product_id integer
Unique numeric identifier of the product id linked to the Membership as it appears in external platforms.
external_variant_id integer
Unique numeric identifier of the variant id linked to the Membership as it appears in external platforms.
presentment_currency string
The presentment currency of the subscription.
price string
The price of the item before discounts, taxes, or shipping have been applied.
quantity integer
The quantity of the subscription.
Request
curl --location --request POST 'https://api.rechargeapps.com/memberships/{id}/change' \
--header 'X-Recharge-Version: 2021-11' \
--header 'Content-Type: application/json' \
--header 'X-Recharge-Access-Token: {api_token}' \
--data-raw '{
"membership_program_id": 123,
"charge_interval_frequency": 30,
"charge_interval_unit": "day",
"external_product_id": "123456789",
"external_variant_id": "987654321",
"presentment_currency": "USD",
"price": 25.00,
"quantity": 1
}'
Response
{
"membership": {
"id": 3580,
"address_id": 103274284,
"customer_id": 94496106,
"membership_program_id": 123,
"purchase_item_id": 279961401,
"cancellation_reason": null,
"cancellation_reason_comments": null,
"cancelled_at": null,
"charge_interval_frequency": "30",
"charge_interval_unit": "day",
"created_at": "2023-02-01T21:57:01+00:00",
"deleted_at": null,
"expires_at": "2023-04-13T12:00:00+00:00",
"external_product_id": 123456789,
"external_variant_id": 987654321,
"has_queued_charges": true,
"next_charge_scheduled_at": "2023-04-13T00:00:00",
"presentment_currency": "USD",
"price": 49.0,
"product_title": "Happy Socks VIP",
"purchase_item_status": "active",
"purchase_item_type": "membership_subscription",
"quantity": 1,
"status": "active",
"type": "membership_subscription",
"updated_at": "2023-03-13T16:04:14+00:00",
"variant_title": ""
}
}
Updated 5 months ago