🔒 Requires read-subscriptions or write-subscriptions and read-customers or write-customers access scope.

The subscription's object

{
    "id": 41,
    "contract_id": "gid://shopify/SubscriptionContract/16557375762",
    "subscriber": {
        "id": "6964807663890",
        "email": "cheetos@recurpay.com",
        "first_name": "cheetos",
        "last_name": "c",
        "phone": "+12025550151",
        "total_spent": 1200,
        "note": "Hello merchant!",
        "addresses": [{
            "first_name": "Cheetos",
            "last_name": "C",
            "email": "cheetos@recurpay.com",
            "phone": "+12025550151",
            "address1": "17718 Sherman Way",
            "address2": null,
            "company": null,
            "city": "Los Angeles",
            "zip": "91335",
            "province": "California",
            "country": "United States"
        }],
        "default_address": {
            "first_name": "Cheetos",
            "last_name": "C",
            "email": "cheetos@recurpay.com",
            "phone": "+12025550151",
            "address1": "17718 Sherman Way",
            "address2": null,
            "company": null,
            "city": "Los Angeles",
            "zip": "91335",
            "province": "California",
            "country": "United States"
        },
        "channel": "ecommerce",
        "meta": [],
        "created_at": "2023-06-05 17:26:16",
        "updated_at": "2024-07-04 14:23:24"
    },
    "status": "cancelled",
    "cancelled_reason": "Onetime contract is over",
    "cancelled_at": "1720000946",
    "delivery_policy": {
        "frequency": 1,
        "interval": "month",
        "auto_expire": {
            "frequency": null,
            "interval": null
        },
        "anchors": [],
        "pre_anchor_behavior": null,
        "cutoff": null
    },
    "billing_policy": {
        "frequency": 1,
        "interval": "month"
    },
    "discount_codes": [{
        "title": "TEST20"
    }],
    "delivery_method": {
        "type": "recurpay_flat_rate",
        "option": "shipping",
        "title": "Standard Shipping",
        "price": 5,
        "currency": "USD"
    },
    "line_items": [{
        "id": 41,
        "product_id": "8441674629394",
        "variant_id": "45703992639762",
        "title": "Amorearth Desi Gir Cow A2 Cultured Ghee",
        "variant_title": "250 / Standard",
        "variant_image_url": "https://cdn.shopify.com/s/files/1/0748/3087/2850/products/tenor_1.gif?v=1689570509",
        "name": "Amorearth Desi Gir Cow A2 Cultured Ghee - 250 / Standard",
        "quantity": 1,
        "price": 2500,
        "properties": [{
            "name": "_recurpay_line_id",
            "value": 41
        }],
        "pricing_polices": [{
            "discount": {
                "type": "percentage",
                "value": 0
            }
        }],
        "is_onetime": false
    }],
    "note": "hello merchant",
    "note_attributes": [],
    "shipping_address": {
        "first_name": "chetan",
        "last_name": "r",
        "email": "cheeeeets@gmail.com",
        "phone": "+12025550151",
        "address1": "17718 Sherman Way",
        "address2": null,
        "company": null,
        "city": "Los Angeles",
        "country": "United States",
        "province": "California",
        "zip": "91335",
        "phone_prefix": null,
        "phone_country_code": null
    },
    "billing_address": {
        "first_name": "chetan",
        "last_name": "r",
        "email": "cheeeeets@gmail.com",
        "phone": "+12025550151",
        "address1": "17718 Sherman Way",
        "address2": null,
        "company": null,
        "city": "Los Angeles",
        "country": "United States",
        "province": "California",
        "zip": "91335",
        "phone_prefix": null,
        "phone_country_code": null
    },
    "payment_method": {
        "gateway": "shopify_payments",
        "mode": "shopify_payments",
        "currency": "USD"
    },
    "orders_count": 6,
    "last_billing_at": "2024-07-03 15:32:26",
    "next_billing_at": "2024-07-03 15:32:26",
    "subscribed_at": "2024-02-07 16:38:53",
    "halted_at": null,
    "last_halted_retried_at": null,
    "halted_retries_count": null,
    "is_skipped": false,
    "skipped_at": null,
    "created_at": "2024-02-07 16:38:53",
    "updated_at": "2024-07-03 15:32:26"
}

The subscription resource

Attribute	Type	Description
id	integer`readonly`	An unsigned 64-bit integer that's used as a unique identifier for the subscription. Each id is unique across the Recurpay system. No two subscriptions will have the same id, even if they're from different stores.
contract_id	string `readonly`	Represents a unique identifier of a Shopify subscription contract, this can be null in case of any other platform than Shopify.
subscriber	array	The customer to whom the subscription belongs. view
status	enum	The current status of the subscription. active: The subscription is active and continuing per its policies. cancelled: The subscription was ended by an unplanned customer's action. paused: When the subscription is paused, all billing and deliveries of the subscriptions are on hold until it is resumed, this means the subscription is temporarily paused and is expected to resume in the future. halted: When the subscription renewal is failed due to payment or internal failures, the subscription status is changed to halted. The renewal retries algorithm tries to renew them as per the defined interval. draft: When the subscription is created via the dashboard it remains on draft until the customer attaches the payment method.
cancelled_reason	string	The cancellation reason of the subscription.
cancelled_at	string	The cancellation date of the subscription.
delivery_policy	object	The delivery policy associated with the subscription. view
billing_policy	object	The billing policy associated with the subscription. view
discount_codes	array	The list of coupon discounts associated with the subscription. view
delivery_method	object	The delivery method for each billing of the subscription. view
line_items	array	The list of subscription line items associated with the subscription. view
note	string	The note field that will be applied to the generated orders.
note_attributes	array	A list of the custom attributes to be added to the generated orders. view
shipping_address	array	The mailing address to where the subscriptionorder will be shipped. This address is optional and will not be available on subscription that do not require shipping. view
billing_address	array	The mailing address associated with the payment method. view
payment_method	object	The customer payment method that's used for the subscription. view
orders_count	integer`readonly`	The number of orders associated with the subscription.
last_billing_at	string `readonly`	The recent billing date of the subscription.
next_billing_at	string	The next billing date for the subscription.
subscribed_at	string	When the subscription was created. The value for this property can be changed.
halted_at	string `readonly`	When the subscription attempted to renew on the next billing date but failed due to payment or product-related issues.
last_halted_retried_at	string `readonly`	The date when a halted subscription was last retried.
halted_retries_count	integer`readonly`	The number of retry attempts made for a halted subscription until its successful renewal.
is_skipped	boolean`readonly`	Indicates whether the subscription has been skipped.
skipped_at	string `readonly`	The date when a subscription was skipped.
created_at	string `readonly`	The autogenerated date and time (ISO 8601 format) when the subscription was created. The value for this property cannot be changed.
updated_at	string `readonly`	The date and time (ISO 8601 format) when the subscription was last modified.

Delivery Policy

Attribute	Type	Description
frequency	integer	The number of intervals between deliveries.
interval	enum	The delivery frequency, it can be either: day, week, month or year.
auto_expire	object	An expiration policy for a subscription that automatically cancels the subscription after a set interval. view
anchors	object	The specific anchor dates upon which the delivery interval calculations should be made. view
pre_anchor_behavior	enum	The fulfilment or delivery behaviour of the first fulfilment is when the order is placed before the anchor. The default value for this field is ASAP.
cutoff	integer	Number of days which represent a buffer period for orders to be included in a cycle.

Auto Expire

Attribute	Type	Description
frequency	integer	The number of intervals between deliveries. Note that it should be multiples of billing frequency.
interval	enum	The auto expire frequency, it can be either: day, week, month or year. Note that it should be same as delivery frequency.

Anchors

Attribute	Type	Description
type	enum	Represents the anchor type, it can be one of WEEKDAY, or MONTHDAY.
value	array	If the type is WEEKDAY the values are to be between Monday - Sunday, and if the type is MONTHDAY the values are to be between 1-31.

Billing Policy

Attribute	Type	Description
frequency	integer	The number of intervals between billings.
interval	enum	The billing frequency, it can be either: day, week, month or year.

Discount Codes

Attribute	Type	Description
title	string	The coupon code which is applied on the subscription.

Delivery Method

Attribute	Type	Description
type	enum	Represents the shipping policy of a subscription. The subscription supports two types of delivery method types: recurpay_flat_rate, offering a fixed delivery price for the subscription, and ecommerce_calculated_rates, which calculates the delivery price according to the ecommerce shipping policy.
option	enum	The option represents how the order is delivered, the available options are: shipping: Order is delivered to the subscription's shipping address. store_pickup: Order to be collected from the local store. local_delivery: Order is delivered from the nearest local store location.
title	string	Title of the delivery method.
price	string	The delivery price for each billing of the subscription.
currency	string	The currency that's used for the delivery price.

Line Items

Attribute	Type	Description
id	integer`readonly`	The ID of the line item.
product_id	integer	The ID of the product that the line item belongs to.
variant_id	integer	The ID of the product variant.
title	string	The title of the product.
name	string	The name of the product variant.
variant_title	string	The title of the product variant.
variant_image	string	The image associated with the line item's variant or product.
quantity	integer	The number of items that were purchased.
price	string	The price of the item before coupon discounts have been applied in the shop currency.
properties	array	List of custom attributes associated to the line item. view
pricing_polices	array	Describe the price changes of the line item such as discounts on top of the variant price. view
is_onetime	boolean	Represents if the line is delivered only once for the upcoming renewal.

Properties

Attribute	Type	Description
name	string	Name of the attribute, for ex: name is Choice of flavor
value	string	Value of the attribute, for ex: value is Vanilla

Pricing Policies

Attribute	Type	Description
discount	array	Represents the discount of a subscription line item. view

Discount

Attribute

Type

Description

type

enum

The type represents how the line item is discounted, the available discount types are:

percentage: Applies a percentage-based discount on the line item price. For example, if the discount is 10%, each unit’s price is reduced by 10%, and the total reflects that across quantity.
fixed: Applies a fixed discount amount per quantity. For example, if the discount is $5 and quantity is 3, then total discount = $15 ($5 × 3).
price: Overrides the price per quantity with a flat amount. For example, if the discount type is price: $250 and quantity is 2, then the total line price becomes $500 ($250 × 2), regardless of the original unit price.

value

string

The percentage value of a line item's pricing policy.

Note Attributes

Attribute	Type	Description
name	string	Name of the attribute, for ex: name is Preferred Time Of Delivery
value	string	Value of the attribute, for ex: value is 10 AM - 5 PM

Address

Attribute	Type	Description
first_name	string	The subscriber's first name.
last_name	string	The subscriber's last name.
email	string	The email address of the subscriber.
phone	string	The subscriber's phone number at this address.
address1	string	The first line of the subscriber's mailing address.
address2	string	An additional field for the subscriber's mailing address.
company	string	The subscriber's company.
city	string	The subscriber's city, town, or village.
zip	string	The subscriber's postal code, also known as zip, postcode, Eircode, etc.
province	string	The subscriber's region name. Typically a province, a state, or a prefecture.
country	string	The subscriber's country.

Payment Method

Attribute	Type	Description
gateway	string	The payment gateway name of the subscription payment method.
mode	string	The instrument for this payment method.
currency	string	The currency that's used for the subscription payment.