Create a Subscription

post

https://api-dev.gettrx.com/payments/v1/subscriptions

Create subscriptions

Body Params

customer

string

required

Identifier for the customer associated with the subscription.

defaultPaymentMethod

string

Identifier for the payment method chosen for the subscription.

site

string

Identifier for the site associated with the subscription.

billingCycleAnchorDate

int64

Anchor date for the billing cycle. Also represents the first date in which an invoice will be charged. Can only be a date in the future. Cannot be combined with trials

collectionMethod

string

enum

Defaults to charge_automatically

Method of collecting payment for the subscription.

charge_automatically : will create invoices and attempt to charge them automatically based on the payment method

send_invoice (comming soon): will create invoices and send them out via email with a link for customers to pay them

Allowed:

daysUntilDue

integer

Days until payment is due. Only applicable when using "send_invoice" as the "collectionMethod"

paymentBehavior

string

enum

Controls the subscription behavior of the during the initial payment.

"error_if_incomplete": prevent creating the subscription when initial invoice payment fails due to bad payment method or lack of one. Initial invoice which was created in memory to execute the charge will also not be stored

"allow_incomplete": creates the subscription in incomplete status even when the initial invoice payment fails due to the reasons stated above. The subscription is created in "incomplete" status. The customer update the payment method of the subscription and complete the payment within 23hrs or else the subscription will be cancelled.

Allowed:

cancelAtPeriodEnd

boolean

Indicates if the subscription should be canceled at the end of the current period.

cancelOn

int64

Unix timestamp to schedule when to cancel the subscription. Must be a date in the future.

trialEnd

int64

Unix timestamp to schedule when the subscription trial will end. Must be a date in the future. Cannot be combined with "trialPeriodDays"

trialPeriodDays

integer

Number of days to be added to current day to determine the date when the trial will end. Cannot be combined with "trialEnd".

accountFees

array of strings

List of account fee ids that will be used to adjust the total price. Used to support cash discount, dual pricing, surcharging mode. Limited to max of 5 account fees.

accountFees

accountDiscounts

array of strings

List of account discount ids that will be used to adjust the total price. Used to support cash discount, dual pricing, surcharging mode. Limited to max of 5 account discounts

accountDiscounts

accountFeeAndDiscountDisplayLayout

string

enum

Determines the invoice layout.

surcharge : Uses surcharge invoice style (i.e. fees/discounts applied as line-items after the subtotal)

dual_pricing: Uses dual pricing invoice style (i.e. fees/discounts applied at the product level. Displays a card amount and a cash amount for each item)

Allowed:

recurringItems

array of objects

Array containing a list of recurring subscription items.

recurringItems

oneTimeItems

array of objects

Array containing a list of recurring subscription items.

oneTimeItems

oneTimeItemsBillingBehavior

string

enum

Determines wether the one time items passed on the API call will be billed immediately or on the next invoice period.

"bill_immediately": immediately triggers a one-time invoice on the subscription to bill for the one-time items passed on the API call.

"bill_on_next_period": oneTimeItems will be billed on the invoice generated for the next period.

Allowed:

paymentMethodTypes

array of strings

List that determines what payment methods are allowed to be used with the subscription. Allows "card" and "us_bank_acount"

paymentMethodTypes

moto

boolean

Set to true when the initial subscription payment is run by the Merchant as a MOTO transaction (e.g. mail order, telephone order, or keyed-in transactions through a virtual terminal).

expand

array of strings

Use to expand the details of the "initialPaymentRequest", or "initialSetupRequest" originated during the creation of the subscription.

expand

metadata

json

Free form json object that allows you to pass custom data in the request to be stored with the subscription object

Headers

idempotencyKey

string

A unique identifier to ensure the same operation isn't processed multiple times, preventing duplicate transactions.

onBehalfOf

string

Specifies the account for which creating a price is intended. This is used for scenarios where one partner creates price on behalf of another partner, such as in PayFac or related partner relationships

Responses

201Success

400400

401401