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 about 1 year ago