> ## Documentation Index > Fetch the complete documentation index at: https://docs.slm.m1amdocs.com/llms.txt > Use this file to discover all available pages before exploring further. # The Subscription Object ## V2 This topic shows information relevant specifically for Subscribe REST API version 20210401 referred to as V2 ## Attributes | Name | Type | Description | | - | - | - | | object | string | Value is “Subscription” | | id | string | A merchant-specified unique identifier. Optionally, this object can be identified by its vid. Using a unique custom identifier is strongly encouraged. | | vid | string | A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe. | | created | datetime | The date/time at which the subscription was requested. | | account | [Account](Accounts) | The account receiving the subscription. | | billing\_plan | [Billing Plan](Billing_Plans) | The billing plan assigned to this subscription. Dictates billing schedule. | | payment\_method | [Payment Method](Payment_Methods) | The payment method assigned to pay for this subscription. | | currency | string | An ISO 4217 Currency Code. A subscription’s charges must be in a single currency. | | description | string | An optional customer-facing identifier or descriptive name for the subscription | | status | enum | The status of the subscription from a service and entitlement perspective. Values can be - `Active`: The Subscription is actively granting entitled service and billing in accordance with the assigned Billing Plan and associated Subscription Items. - `Cancelled`: The Subscription is no longer actively granting service. It has been cancelled due to user, merchant, or system action—for example, the customer has opted out of recurring billing or canceled the service; API calls to cancel the subscription or stop billing on the Customer have been made; or if a chargeback is received against a transaction generated by the Subscription. Cancelled is a terminal and permanent status. The Billing condition of this Subscription is clarified by the current Billing State. Note that the customer who owns the Subscription is entitled until the Subscription's end-date. - `Deleted`: The Subscription was administratively removed—the content of this status can only be displayed in custom and specialty reports. - `Expired`: The Subscription is no longer actively granting service—its fixed or non-recurring plan has ended and no further billing is scheduled or possible. - `Pending Activation`: The Subscription has been fully created, has a start date that is in the future, and has not yet granted entitled service and is not yet billing. The Subscription start date can still be changed. - `Pending Cancel`: The Subscription is Active but scheduled for cancellation. The Subscription will leave active service at the current end date. - `Processing`: The Subscription is newly created and still being administratively defined. It is not currently providing entitled service and is not yet billing. Typically this status will be followed by Pending Activation where the Subscription has been completely created but has a future start date and is not yet entitled or billing. - `Pending Pause`: The Subscription is Active but scheduled for pause. The Subscription will be paused on the next pause\_history sub-object start date. It will remain paused with no end date. - `Paused`: The Subscription is no longer actively granting service or being billed. If no other action is taken upon the Subscription (resume is not performed), it will remain paused for 5 years, and then automatically move to `Cancelled` status. | | billing\_state | enum | The billing status presents the financial billing condition of the Subscription. When used in combination with the status field, it provides a definitive representation of the current condition of a Subscription. - `Unknown`: For internal use or test purposes. - `Good Standing`: Billing for the current billing period was successful - `Free/Trial`: The subscriptions current Billing Period definition (as specified by the current Billing Plan) is forcibly free. This can be a temporary state or for the duration of the billing period configured to be free-or permanent if the Billing Plan is permanently free. This state does not apply when the free condition is arrived at due to a Campaign application. - `In Retry`: The Subscription is still active but in retry, and has at least one billing period in which there was a failed attempt to charge; the Subscription is still within the configured retry period and may yet be saved by automated processes or customer action. This state corresponds to the prior Soft Error status. In the new scheme, it will only be paired with the Active status. - `Unusable PaymentMethod`: The Subscription is still active but is in retry, and has at least one billing period in which there was a failed attempt to charge, and received an error code designated as a Hard Fail, which is expected to be unrecoverable. The Subscription will remain in this state, in the expectation that a new payment method will be provided by the customer, until the specified retry, or grace period, expires. This state corresponds to the previous Hard Error status when the subscription end date has not passed. - `Billing Completed`: The Subscription is not active; it successfully completed all required billing and has no further scheduled billings. - `Failed To Collect`: The Subscription is no longer active, having exhausted the retry period without a successful payment method update. This state corresponds to the previous Hard Error status, in which the Subscription end date has passed. This state will only exist for an Subscription with the status: Canceled. - `Overdue`: The Subscription is assigned a Merchant Accepted Payment (MAP) payment method (invoicing) and has at least one overdue invoice. - `Pending Acceptance`: The Subscription uses a payment method that requires merchant or customer action before charges can be processed, and is waiting on that external action or approval. - `Free Period`: The Subscription is currently in a free or \$0 billing period for any period excepting a Free=True condition on the initial billing period only, (which uses the Free/Trial state). - `Terminated`: The Subscription has been forced into a terminal state by system or merchant action. No further billing is planned. - `Grace Period`: The subscription has an unpaid balance and is in the retry period but has passed the last scheduled retry attempt-the only path to recovery is a successful payment method update (usually customer intervention). The Subscription is still active and entitled until the end of the Grace Period. - `Paused`: The Subscription is no longer actively being billed. If no other action is taken upon the Subscription (resume is not performed), it will remain paused for 5 years, and then automatically move to `Billing Completed` status when the service status moves to cancelled. - `Pending Resume`: A paused subscription can be changed to pending resume. The Subscription will resume active billing and associated Entitlements will be granted at the beginning of the next billing cycle. - `Legacy Unknown BillingState`: For internal use or test purposes only. - `Unbilled`: No billing has yet occurred for this subscription. | | starts | datetime | The date/time the subscription starts service. | | ends | datetime | The date/time the subscription ends service. | | entitled\_through | datetime | The date/time to which the subscription will entitle service if no further payments are made – a “paid thru” date based on billing schedule and grace period. | | items | [Subscription Item](Subscription_Item) | The product-based line items for the subscription. | | source\_ip | string | Optional source IP Address at sign-up. | | billing\_descriptor | string | Optional “soft descriptor” to send to the payment processor for transactions from this subscription. | | billing\_day | integer | The day of the month on which the subscription is (typically) billed. Often called an “anniversary date.” | | minimum\_commitment | integer | Number of billing cycles customer is obligated to maintain the subscription. Cancelling before this time requires merchant to “force” cancellation. | | affiliate | string | Affiliate or channel identifier, if any, under which the subscription was submitted. | | sub\_affiliate | string | A more granular or subordinate affiliate identifier. | | notify\_on\_transition | boolean | Indicates whether to send an expiration or trial-end email notification using the days-in-advance configuration in the Billing Plan. | | most\_recent\_billing | [Transaction](Transactions) | The Transaction processed when creating a new Subscription `(POST subscriptions)`, which includes a charge for the initial billing periodor The Transaction processed when updating an existing subscription `(POST subscriptions:subscription)`, which results in a charge for the current billing period . | | most\_recent\_refunds | [Refund array](Refunds) | A list of refund objects processed when updating an existing Subscription `(POST /subscriptions/:subscription)`, which results in a net refund for the current billing period. | | next\_billing | [Transaction](Transactions) | The next scheduled billing transaction expected for the subscription. | | metadata | hash | A set of key/value pairs that you can attach to an object. Useful for storing additional information. Subscription metadata will be inherited by resulting transactions. | | credit | [Credit](Credits) | Credit balance of the subscription. | | statement\_format | enum | Instructions for if/how to include the invoice statement for this subscription. Values can be `Attachment`, `DoNotSend`, `Inline` | | invoice\_terms | integer | Net Terms (in days); after this many days from a billing, the invoice will be considered delinquent. | | statement\_offset | integer | Days before scheduled billing to deliver the statement. | | statement\_template | string | Template to use for statement generation. | | billing\_plan\_campaign\_code | string | The Campaign code redeemed on this Subscription against the price of the Billing Plan. To apply a Campaign, use this field to pass in a valid Coupon or Promotion code.**Note:** This data member will not be returned in response | | billing\_plan\_campaign\_id | string | The unique identifier for a Campaign applied to this Subscription’s BillingPlan. This is a read-only field returned by Subscribe for informational purposes. Values sent in with a SOAP call will be ignored. **Note:** Read only. | | billing\_plan\_discount\_tickets | [Discount Tickets](Discount_Tickets) | Discount Tickets offer the ability to redeem multiple campaign discounts. This attribute is an array of Discount Tickets applicable to this subscription's Billing Plan. | | unknown\_starts | boolean | The attribute used to create a Subscription Pending Activation. | | balance | decimal | | | mandate | [Mandate](Mandate) | Direct Debit mandate on file for this subscription, if any. | | cancel\_reason | [Cancel Reason](Cancel_Reasons) | Code for the reason a subscription was cancelled. Codes must be pre-defined by merchants or use the pre-built codes available. | | policy | hash | The policy object governing Subscription behavior. | | policy: ignore\_cvn\_policy | boolean | Indicates whether to evaluate any custom or default CVN (card security code) policy. | | policy: ignore\_avs\_policy | boolean | Indicates whether to evaluate any custom or default AVS (card Address Verification Service) policy. | | policy: min\_chargeback\_probability | integer | If Chargeback Probability from risk scoring is greater than this, the transaction will fail. Default is 100. | | policy: immediate\_auth\_failure\_policy | enum | How to respond to Authorization failure while processing first Transaction for a Subscription. Values can be `doNotSaveAutoBill`, `putAutoBillInRetryCycle`, `putAutoBillInRetryCycleIfPaymentMethodIsValid`. Defaults to doNotSaveAutoBill if unspecified. | | policy: campaign\_code | [Campaign code](Campaign_Codes) | An optional Coupon or Promotion code to be applied to any applicable items in the subscription in order to provide a discount. | | policy: discount\_tickets\_to\_distribute | [Discount Tickets](Discount_Tickets) | An array of Discount Tickets to be applied to any applicable items in the subscription in order to provide a discount. | | policy: validate\_for\_future\_payment | boolean | Validate the payment method for future payments if initial Transaction is not being created/Authorized. Subscription will not be saved if validation is requested and fails. | | policy: enable\_3ds | boolean | Enable the 3DS payment standard for strong customer authentication. A merchant configuration serves as a higher level indication whether 3DS is used by the merchant. When available for use, you can enable 3DS flow per subscription, transaction, or payment method. | | policy: full\_auth\_delayed\_capture | boolean | When enabled, the Subscription will be created with an `auth` for the full amount of the first paid-for period. | ## Example Object ``` { "object": "Subscription", "id": "sub_1234", "vid": "796db5f7f7a1dea312f6c7e1393aebec1f1ecf1b", "account": {...}, "billing_plan": {...}, "payment_method": {...}, "currency": "USD", "description": "Subscription_1234", "status": "Active", "billing_state": "Good Standing", "starts": "2020-05-27T05:52:02-07:00", "items": { "object": "List", "data": [ { "object": "SubscriptionItem", "id": "sub_1234.1", "vid": "6b0fbf093f5325f25b625d132520b7b96aef7bdf" "index": 0, "product": {...}, "quantity": 1, "created": "2020-05-27T05:52:02-07:00", "starts": "2020-05-27T00:00:00-07:00" }, { "object": "SubscriptionItem", "id": "sub_1234.2", "vid": "5d0abf223t8524a25a651v126531b9v66nef2wcf" "index": 1, "product": {...}, "quantity": 1, "created": "2020-05-27T05:52:02-07:00", "starts": "2020-05-27T00:00:00-07:00" } ], "total_count": 2 }, "billing_day": 20 "minimum_commitment": 0, "notify_on_transition": true, "most_recent_billing": {...} "next_billing": {...} } ``` ``` { "object": "Subscription", "id": "sub_1234", "vid": "796db5f7f7a1dea312f6c7e1393aebec1f1ecf1b", "account": {...}, "billing_plan": {...}, "payment_method": {...}, "currency": "USD", "description": "Subscription_1234", "status": "Active", "billing_state": "Good Standing", "starts": "2020-05-27T05:52:02-07:00", "items": { "object": "List", "data": [ { "object": "SubscriptionItem", "id": "sub_1234.1", "vid": "6b0fbf093f5325f25b625d132520b7b96aef7bdf" "index": 0, "product": {...}, "quantity": 1, "created": "2020-05-27T05:52:02-07:00", "starts": "2020-05-27T00:00:00-07:00" }, { "object": "SubscriptionItem", "id": "sub_1234.2", "vid": "5d0abf223t8524a25a651v126531b9v66nef2wcf" "index": 1, "product": {...}, "quantity": 1, "created": "2020-05-27T05:52:02-07:00", "starts": "2020-05-27T00:00:00-07:00" "discount_tickets": { "object": "List", "data": [ { "object": "DiscountTicket", "id": "ITMIX1_3rx1N36WaGcaXCrYa_ddBcSYM2U", "vid": "408152f7ee36fdbd9c81a085275d2f3fe770ab45", "campaign_code": "99BU", "state": "Active", "added_date": "2021-06-18T13:49:12-07:00", "start_billing_sequence": 0, "end_billing_sequence": 1, "campaign_id": "COUP1_campaign_mbjUhpf-vf_dV1wabhfexablOb4" } ], "total_count": 1 } ], "total_count": 2 }, "billing_day": 20 "minimum_commitment": 0, "notify_on_transition": true, "most_recent_billing": {...} "next_billing": {...} } ``` **Parent topic:**[Subscriptions](../topics/Subscriptions) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.