Subscriptions

In Lemon Squeezy, a subscription is created when a subscription product is purchased and will bill the customer on a recurring basis.

A subscription belongs to a Store and is associated with an Order, an Order Item, a Product and a Variant.

The subscription object

Attributes

store_id

The ID of the store this subscription belongs to.

order_id

The ID of the order associated with this subscription.

order_item_id

The ID of the order item associated with this subscription.

product_id

The ID of the product associated with this subscription.

variant_id

The ID of the variant associated with this subscription.

product_name

The name of the product.

variant_name

The name of the variant.

user_name

The full name of the customer.

user_email

The email address of the customer.

status

The status of the subscription. One of on_trialactivecancelledexpired.

status_formatted

The formatted status of the subscription.

ends_at

If the subscription has been cancelled, this will be an ISO-8601 formatted date-time string indicating when the subscription expires.

created_at

An ISO-8601 formatted date-time string indicating when the object was created.

updated_at

An ISO-8601 formatted date-time string indicating when the object was last updated.

Subscription object

{
  "type": "subscriptions",
  "id": "1",
  "attributes": {
    "store_id": 1,
    "order_id": 1,
    "order_item_id": 1,
    "product_id": 1,
    "variant_id": 1,
    "product_name": "Example Product",
    "variant_name": "Example Variant",
    "user_name": "Darlene Daugherty",
    "user_email": "gernser@yahoo.com",
    "status": "active",
    "status_formatted": "Active",
    "ends_at": null,
    "created_at": "2021-08-11T13:47:27.000000Z",
    "updated_at": "2021-08-11T13:54:19.000000Z"
  }
}

Retrieve a subscription

Retrieves the subscription with the given ID.

Returns

Returns a subscription object.

GET /v1/subscriptions/:id

curl "https://api.lemonsqueezy.com/v1/subscriptions/1" \
     -H 'Accept: application/vnd.api+json' \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer {api_key}'

Response

{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1"
  },
  "data": {
    "type": "subscriptions",
    "id": "1",
    "attributes": {
      "store_id": 1,
      "order_id": 1,
      "order_item_id": 1,
      "product_id": 1,
      "variant_id": 1,
      "product_name": "Example Product",
      "variant_name": "Example Variant",
      "user_name": "Darlene Daugherty",
      "user_email": "gernser@yahoo.com",
      "status": "active",
      "status_formatted": "Active",
      "ends_at": null,
      "created_at": "2021-08-11T13:47:27.000000Z",
      "updated_at": "2021-08-11T13:54:19.000000Z"
    },
    "relationships": {
      "store": {
        "links": {
          "related": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/store",
          "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/relationships\/store"
        }
      },
      "order": {
        "links": {
          "related": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/order",
          "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/relationships\/order"
        }
      },
      "order-item": {
        "links": {
          "related": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/order-item",
          "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/relationships\/order-item"
        }
      },
      "product": {
        "links": {
          "related": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/product",
          "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/relationships\/product"
        }
      },
      "variant": {
        "links": {
          "related": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/variant",
          "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/relationships\/variant"
        }
      }
    },
    "links": {
      "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1"
    }
  }
}

List all subscriptions

Returns a paginated list of subscriptions.

Parameters

store_id

Only return subscriptions belonging to the store with this ID.

order_id

Only return subscriptions belonging to the order with this ID.

order_item_id

Only return subscriptions belonging to the order item with this ID.

product_id

Only return subscriptions belonging to the product with this ID.

variant_id

Only return subscriptions belonging to the variant with this ID.

Returns

Returns a paginated list of subscription objects ordered by created_at (descending).

GET /v1/subscriptions

curl "https://api.lemonsqueezy.com/v1/subscriptions" \
     -H 'Accept: application/vnd.api+json' \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer {api_key}'

Response

{
  "meta": {
    "page": {
      "currentPage": 1,
      "from": 1,
      "lastPage": 1,
      "perPage": 10,
      "to": 10,
      "total": 10
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-createdAt",
    "last": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-createdAt",
  },
  "data": [
    {
      "type": "subscriptions",
      "id": "1",
      "attributes": {
        "store_id": 1,
        "order_id": 1,
        "order_item_id": 1,
        "product_id": 1,
        "variant_id": 1,
        "product_name": "Example Product",
        "variant_name": "Example Variant",
        "user_name": "Darlene Daugherty",
        "user_email": "gernser@yahoo.com",
        "status": "active",
        "status_formatted": "Active",
        "ends_at": null,
        "created_at": "2021-08-11T13:47:27.000000Z",
        "updated_at": "2021-08-11T13:54:19.000000Z"
      },
      "relationships": {
        "store": {
          "links": {
            "related": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/store",
            "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/relationships\/store"
          }
        },
        "order": {
          "links": {
            "related": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/order",
            "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/relationships\/order"
          }
        },
        "order-item": {
          "links": {
            "related": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/order-item",
            "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/relationships\/order-item"
          }
        },
        "product": {
          "links": {
            "related": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/product",
            "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/relationships\/product"
          }
        },
        "variant": {
          "links": {
            "related": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/variant",
            "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1\/relationships\/variant"
          }
        }
      },
      "links": {
        "self": "https:\/\/api.lemonsqueezy.com\/v1\/subscriptions\/1"
      }
    },
    {...},
    {...},
  ]
}