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.

1209

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": ""
    }
}

Need Help? Contact Us