Represents a Subscription.
🔒 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": "[email protected]",
"first_name": "cheetos",
"last_name": "c",
"phone": "+12025550151",
"total_spent": 1200,
"note": "Hello merchant!",
"addresses": [{
"first_name": "Cheetos",
"last_name": "C",
"email": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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,
"created_at": "2024-02-07 16:38:53",
"updated_at": "2024-07-03 15:32:26"
}
The subscription resource
| Attribute | Type | Description |
|---|---|---|
| id | integerreadonly | 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 | integerreadonly | 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 | integerreadonly | The number of retry attempts made for a halted subscription until its successful renewal. |
| 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_rates, offering a fixed delivery price for the subscription, and ecommerce_calculated_price, 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 | integerreadonly | 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 subscription line item supports a pricing policy of percentage-off adjustments. |
| 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. |
| 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. |