Subscription

Type:  
Abstract:  no
Status:  Active
Java Class:  Subscription
Information about the subscription transaction.
Available Fields:
id
References: Payment Plan.Id
XML Representation: attribute
Attributes: ReadOnly
Default Value
Identifier of the object used for references; auto-incremented integer value.

**create Unique identifier of the subscription automatically generated by the system.\n\r\n> **Note:** This field is typically not included in creation requests as it is assigned by the system.
  • exists System-generated unique identifier for the newly created subscription.\n\r\n> **Note:** Use this identifier in subsequent API calls when referencing this subscription.\n\r\n> **Tip:** Store this value in your system for future subscription management operations.
  • echo System-generated unique identifier for the newly created subscription.\n\r\n> **Note:** Use this identifier in subsequent API calls when referencing this subscription.\n\r\n> **Tip:** Store this value in your system for future subscription management operations.
    • accountId
    References: Payment Plan.Merchant Account Code
    XML Representation: attribute
    Attributes:
    Default Value
    Code of Merchant Account to which instance of this object is attributed to. Depending on the context, Merchant Account Code field may contain either Merchant Code or Merchant Account Code.
    The field is primarily used for data partitioning and data management, to make it easy to determine the ownership of a record within the database.


    **create Reference to the merchant account under which this subscription will be created.\n\r\n> **Note:** Your API credentials may be associated with more than one accountId.
  • exists Identifier of the merchant account under which this subscription was created.\n\r\n> **Note:** This indicates which merchant account is managing this subscription.
  • echo Identifier of the merchant account under which this subscription was created.\n\r\n> **Note:** This indicates which merchant account is managing this subscription.
    • code
    References: Payment Plan.Reference Code
    XML Representation: attribute
    Attributes: CreateOnly
    Default Value
    Pattern: CODE
    See Reference Code definition for additional information.

    **create Optional secondary identifier for the subscription that references an ID in your own system.\n\r\n> **Note:** If not provided, this value will default to the subscription's system-generated ID returned in the response.\n\r\n> **Tip:** Use this field to facilitate cross-referencing between systems and simplify reconciliation processes.
  • exists Secondary identifier for the subscription that references an ID in your own system.\n\r\n> **Note:** If you didn't provide a value in the request, this will be set to the same value as the id field.\n\r\n> **Tip:** Use this field to cross-reference subscriptions between systems.
  • echo Secondary identifier for the subscription that references an ID in your own system.\n\r\n> **Note:** If you didn't provide a value in the request, this will be set to the same value as the id field.\n\r\n> **Tip:** Use this field to cross-reference subscriptions between systems.
    • customerId
    References: Payment Plan.Customer Account FK
    XML Representation: attribute
    Attributes:
    Default Value
    Reference to the entity that represents code of the customer account to which instance of this object is attributed to.

    **create Identifier of the customer for whom the subscription is being created.\n\r\n> **Note:** This is derived from the customer-id field and typically does not need to be explicitly provided.
  • exists Identifier of the customer for whom the subscription is being created.\n\r\n> **Tip:** Use this to retrieve customer details or to group all subscriptions for a particular customer.
  • echo Identifier of the customer for whom the subscription is being created.\n\r\n> **Tip:** Use this to retrieve customer details or to group all subscriptions for a particular customer.
    • paymentOptionId
    Type: PaymentOption
    XML Representation: element
    Attributes: Required
    Default Value
    Reference to the entity that represents payment option used to collect money on the payment plan.

    **create Reference to the customer's payment method that will be used to collect subscription payments.\n\r\n> **Note:** This must be a valid payment option ID already created in the system for the customer.\n\r\n> **Tip:** Create a payment option for the customer before creating a subscription if the customer doesn't already have one.
  • exists Reference to the customer's payment method that will be used to collect subscription payments.\n\r\n> **Note:** This is the payment method that will be charged according to the subscription schedule.
  • echo Reference to the customer's payment method that will be used to collect subscription payments.\n\r\n> **Note:** This is the payment method that will be charged according to the subscription schedule.
    • createDate
    References: Payment Plan.Create Date
    XML Representation: attribute
    Attributes: ReadOnly
    Default Value
    Date when the record was created.

    **create Date when the subscription record was created in the system.\n\r\n> **Note:** Format must be yyyy-MM-dd. This field is typically populated by the system rather than provided in the request.
  • exists Date and time when the subscription was created in the system.\n\r\n> **Note:** This value is returned in yyyy-MM-dd HH:mm:ss format.
  • echo Date and time when the subscription was created in the system.\n\r\n> **Note:** This value is returned in yyyy-MM-dd HH:mm:ss format.
    • firstBillingDate
    References: Payment Plan.First Billing Date
    XML Representation: attribute
    Attributes: Required, CreateOnly
    Default Value
    Date when the first billing occured.

    **create Date when the first billing for this subscription should occur.\n\r\n> **Note:** Format must be yyyy-MM-dd. This date determines the billing cycle start date for recurring charges.
  • exists Date when the first billing for this subscription will occur.\n\r\n> **Note:** Format must be yyyy-MM-dd. This date establishes the billing cycle start date.
  • echo Date when the first billing for this subscription will occur.\n\r\n> **Note:** Format must be yyyy-MM-dd. This date establishes the billing cycle start date.
    • type
    References: Payment Plan.Payment Plan CL
    XML Representation: attribute
    Attributes: CreateOnly
    Default Value P
    Enumeration of possible types of payment plans.

    **create Type of subscription being created - either fixed-term or perpetual (ongoing). If this value is set to F (Fixed), you must specify the duration using the length field. For ongoing subscriptions, use P (Perpetual).\n\r\n> **Tip:** Choose F (Fixed) for services with a defined end date and P (Perpetual) for ongoing services.
  • exists Type of subscription - either fixed-term or perpetual (ongoing).\n\r\n> **Note:** F (Fixed) indicates a subscription with a defined end date, while P (Perpetual) indicates an ongoing subscription.
  • echo Type of subscription - either fixed-term or perpetual (ongoing).\n\r\n> **Note:** F (Fixed) indicates a subscription with a defined end date, while P (Perpetual) indicates an ongoing subscription.
    • length
    References: Payment Plan.Length
    XML Representation: attribute
    Attributes: CreateOnly
    Default Value
    Time period when the payment plan is active.

    **create Number of billing cycles for which the subscription will be active. This field is required only when type is set to F (Fixed). Must not exceed the following maximum values, depending on billingCycleType: A (Annual) - 3, S (Semi-annual) - 6, Q (Quarterly) - 12, M (Monthly) - 36, W (Weekly) - 153.\n\r\n> **Tip:** For subscriptions longer than 3 years, use Perpetual (P) subscription type.
  • exists Number of billing cycles for which the subscription will be active.\n\r\n> **Note:** This field is only included for subscriptions with type=F (Fixed). The maximum value depends on the billingCycleType: A (Annual) - 3, S (Semi-annual) - 6, Q (Quarterly) - 12, M (Monthly) - 36, W (Weekly) - 153.
  • echo Number of billing cycles for which the subscription will be active.\n\r\n> **Note:** This field is only included for subscriptions with type=F (Fixed). The maximum value depends on the billingCycleType: A (Annual) - 3, S (Semi-annual) - 6, Q (Quarterly) - 12, M (Monthly) - 36, W (Weekly) - 153.
    • lastBillingDate
    References: Payment Plan.Last Invoicing Date
    XML Representation: attribute
    Attributes: ReadOnly
    Default Value
    Date when the last invoice was created.

    **create Final date when billing will occur for this subscription.\n\r\n> **Note:** Format must be yyyy-MM-dd. This field is typically calculated by the system based on firstBillingDate, type, and length values.
  • exists Final date when billing will occur for this subscription.\n\r\n> **Note:** This field is only included for subscriptions with type=F (Fixed). Format must be yyyy-MM-dd.
  • echo Final date when billing will occur for this subscription.\n\r\n> **Note:** This field is only included for subscriptions with type=F (Fixed). Format must be yyyy-MM-dd.
    • amount
    References: Payment Plan.Amount
    XML Representation: attribute
    Attributes:
    Default Value
    The amount of money charged every time billing occurs for this payment plan (e.g. amount of the transaction). Value must be submitted in cents without a decimal point.

    **create Amount (in cents) to charge for each billing cycle of this subscription.\n\r\n> **Note:** This is typically derived from the referenced plan and does not need to be explicitly provided.
  • exists Amount (in cents) that will be charged for each billing cycle of this subscription.\n\r\n> **Note:** For example, $10.00 would be represented as 1000.
  • echo Amount (in cents) that will be charged for each billing cycle of this subscription.\n\r\n> **Note:** For example, $10.00 would be represented as 1000.
    • lastUpdateDate
    References: Payment Plan.Last Update Date
    XML Representation: attribute
    Attributes: ReadOnly
    Default Value
    Date when the payment plan was updated for the last time.

    **create Date of the most recent modification to the subscription.\n\r\n> **Note:** This field is typically populated by the system rather than provided in the request.
  • exists Date and time when the subscription was last modified.\n\r\n> **Note:** This value is returned in yyyy-MM-dd HH:mm:ss format. Matches createDate for newly created subscriptions.
  • echo Date and time when the subscription was last modified.\n\r\n> **Note:** This value is returned in yyyy-MM-dd HH:mm:ss format. Matches createDate for newly created subscriptions.
    • note
    References: Payment Plan.Note
    XML Representation: attribute
    Attributes:
    Default Value
    Pattern: TEXT
    Any additional notes related to the payment plan within the system.

    **create Additional information or comments about this subscription.\n\r\n> **Note:** Maximum length is 255 characters.\n\r\n> **Tip:** Use this field to store customer-specific details related to the subscription for internal reference.
  • exists Additional information or comments about this subscription.\n\r\n> **Note:** This field is only included if a note was provided in the request.
  • echo Additional information or comments about this subscription.\n\r\n> **Note:** This field is only included if a note was provided in the request.
    • nextInvoicingDate
    Type: Date
    XML Representation: attribute
    Attributes:
    Default Value
  • create Date when the next invoice will be generated for this subscription.\n\r\n> **Note:** This field is typically calculated by the system rather than provided in the request.
  • exists Date when the next invoice will be generated for this subscription.\n\r\n> **Note:** Format must be yyyy-MM-dd. This field is only included if relevant to the subscription's current state.
  • echo Date when the next invoice will be generated for this subscription.\n\r\n> **Note:** Format must be yyyy-MM-dd. This field is only included if relevant to the subscription's current state.
    • nextBillingDate
    References: Billing Cycle.Next Billing Date
    XML Representation: attribute
    Attributes:
    Default Value
    Date when the next billing will occur.

    **create Date when the next billing will occur for this subscription.\n\r\n> **Note:** Format must be yyyy-MM-dd. This field is typically calculated by the system based on the billing cycle.
  • exists Date when the next billing will occur for this subscription.\n\r\n> **Note:** Format must be yyyy-MM-dd. This value is automatically calculated based on the billing cycle and the firstBillingDate.
  • echo Date when the next billing will occur for this subscription.\n\r\n> **Note:** Format must be yyyy-MM-dd. This value is automatically calculated based on the billing cycle and the firstBillingDate.
    • pendingAdjustmentType
    References: Payment Plan.Pending Adjustment Cl
    XML Representation: attribute
    Attributes: ReadOnly
    Default Value
  • create Type of scheduled change to be applied to this subscription.\n\r\n> **Note:** Include this field only when scheduling future changes to an existing subscription.\n\r\n> **Tip:** Use this field with pendingAdjustmentEffectiveDate to schedule subscription changes in advance.
  • exists Type of scheduled change to be applied to this subscription.\n\r\n> **Note:** This field is only included if a future adjustment has been scheduled.\n\r\n> **Tip:** Common values include F (Freeze), C (Cancel), or P (Pause).
  • echo Type of scheduled change to be applied to this subscription.\n\r\n> **Note:** This field is only included if a future adjustment has been scheduled.\n\r\n> **Tip:** Common values include F (Freeze), C (Cancel), or P (Pause).
    • planId
    Type: Plan
    XML Representation: element
    Attributes: CreateOnly
    Default Value
  • create Reference to the payment plan the customer is subscribing to.\n\r\n> **Note:** This must be a valid payment plan ID already created in the system.\n\r\n> **Tip:** The referenced plan determines the billing amount and available billing cycle options.
  • exists Reference to the payment plan this subscription is based on.\n\r\n> **Note:** The plan defines the base pricing and billing terms for this subscription.
  • echo Reference to the payment plan this subscription is based on.\n\r\n> **Note:** The plan defines the base pricing and billing terms for this subscription.
    • planName
    References: Plan.Name
    XML Representation: attribute
    Attributes: ReadOnly
    Default Value
    Name of the plan.

    **create Name of the payment plan associated with this subscription.\n\r\n> **Note:** This field is typically derived from the planId and does not need to be explicitly provided in the request.
  • exists Name of the payment plan associated with this subscription.\n\r\n> **Note:** This value is derived from the referenced planId and provides a human-readable identifier.
  • echo Name of the payment plan associated with this subscription.\n\r\n> **Note:** This value is derived from the referenced planId and provides a human-readable identifier.
    • status
    References: Payment Plan.Status CL
    XML Representation: attribute
    Attributes: ReadOnly
    Default Value U
    Represents current (or selected) status of the payment plan.



    **create Current status of the subscription in the system.\n\r\n> **Note:** This field is typically populated by the system rather than provided in the request.
  • exists Current status of the subscription in the system.\n\r\n> **Note:** For new subscriptions, this is typically set to "Current" or "Unbilled" depending on the billing schedule.
  • echo Current status of the subscription in the system.\n\r\n> **Note:** For new subscriptions, this is typically set to "Current" or "Unbilled" depending on the billing schedule.
    • billingCycleType
    References: Plan.Billing Cycle Cl
    XML Representation: attribute
    Attributes: CreateOnly
    Default Value
    Reference to the entity that represents billing cycle associated with the plan.

    **create Frequency at which the customer will be billed for this subscription.\n\r\n> **Note:** Default: `M` (Monthly). Other options include A (Annual), S (Semi-annual), Q (Quarterly), and W (Weekly).\n\r\n> **Tip:** This typically should match the billing cycle type defined in the referenced plan.
  • exists Frequency at which the customer will be billed for this subscription.\n\r\n> **Note:** Common values include M (Monthly), A (Annual), Q (Quarterly), etc.
  • echo Frequency at which the customer will be billed for this subscription.\n\r\n> **Note:** Common values include M (Monthly), A (Annual), Q (Quarterly), etc.
    • pendingAdjustmentEffectiveDate
    References: Payment Plan.Pending Adjustment Effective Date
    XML Representation: attribute
    Attributes:
    Default Value
  • create Date when the scheduled change will take effect. This field is required when pendingAdjustmentType is provided.\n\r\n> **Note:** Format must be yyyy-MM-dd.
  • exists Date when the scheduled change will take effect.\n\r\n> **Note:** Format must be yyyy-MM-dd. This field is only included if pendingAdjustmentType is present.
  • echo Date when the scheduled change will take effect.\n\r\n> **Note:** Format must be yyyy-MM-dd. This field is only included if pendingAdjustmentType is present.
    • pendingAdjustmentNote
    References: Payment Plan.Pending Adjustment Note
    XML Representation: attribute
    Attributes: Required
    Default Value
    Pattern: TEXT
  • create Additional information about the scheduled adjustment. This field is required if any of the pendingAdjustment fields are provided.\n\r\n> **Note:** Maximum length is 255 characters.
  • exists Additional information about the scheduled adjustment.\n\r\n> **Note:** This field is only included if pendingAdjustmentType is present.
  • echo Additional information about the scheduled adjustment.\n\r\n> **Note:** This field is only included if pendingAdjustmentType is present.
    • pendingAdjustmentLength
    References: Payment Plan.Pending Adjustment Length
    XML Representation: attribute
    Attributes: ReadOnly
    Default Value
  • create Number of billing cycles for which the adjustment will apply. This field is required when pendingAdjustmentType is F (Freeze).\n\r\n> **Note:** For freeze adjustments, this defines how many billing cycles to skip.
  • exists Number of billing cycles for which the adjustment will apply.\n\r\n> **Note:** This field is only included if pendingAdjustmentType is F (Freeze).
  • echo Number of billing cycles for which the adjustment will apply.\n\r\n> **Note:** This field is only included if pendingAdjustmentType is F (Freeze).
    • firstInvoicingDate
    Type: Date
    XML Representation: attribute
    Attributes:
    Default Value
  • create Date when the first invoice will be generated for this subscription.\n\r\n> **Note:** Format must be yyyy-MM-dd. This may differ from firstBillingDate if you want to generate invoices before collecting payment.
  • exists Date when the first invoice will be generated for this subscription.\n\r\n> **Note:** Format must be yyyy-MM-dd. This field is only included if invoicing is configured separately from billing.
  • echo Date when the first invoice will be generated for this subscription.\n\r\n> **Note:** Format must be yyyy-MM-dd. This field is only included if invoicing is configured separately from billing.
    • taxAmount
    References: Payment Plan.
    XML Representation: attribute
    Attributes:
    Default Value
  • create Tax amount (in cents) to be applied to each billing cycle.\n\r\n> **Note:** This is typically derived from the referenced plan and does not need to be explicitly provided.
  • exists Tax amount (in cents) that will be applied to each billing cycle.\n\r\n> **Note:** This field is only included if tax calculation is enabled for this subscription.
  • echo Tax amount (in cents) that will be applied to each billing cycle.\n\r\n> **Note:** This field is only included if tax calculation is enabled for this subscription.

    • XML Sample:

    <object>
    <paymentOptionId accountNumber=""  holderName=""  accountAccessory="" /> firstBillingDate=""  pendingAdjustmentNote="" 
</object>
    "<object> <paymentOptionId accountNumber=\"\" holderName=\"\" accountAccessory=\"\" /> firstBillingDate=\"\" pendingAdjustmentNote=\"\" </object>"

    JSON Sample:

    {
  "paymentOptionId": {
    "accountNumber": "",
    "holderName": "",
    "accountAccessory": ""
  },
  "firstBillingDate": "",
  "pendingAdjustmentNote": ""
}

    XURL Sample:

    ?paymentOptionId.accountNumber=&paymentOptionId.holderName=&paymentOptionId.accountAccessory=&firstBillingDate=&pendingAdjustmentNote=&
    paymentOptionId.accountNumber=
    paymentOptionId.holderName=
    paymentOptionId.accountAccessory=
    firstBillingDate=
    pendingAdjustmentNote=
    Copyright © United Thinkers. (UniPay - Payment Gateway Software)
    All Logos and Trademarks used or mentioned on this page are copyrighted property of their respective owners and are used for display purposes only.