Skip to main content

Create a subscription

POST 
/api/v3/package

Below is a simple example – the new billing package will use the default shipping and billing address from the customer, and the default pricing from the item (item #239). The first invoice won’t be sent until the holduntil_datetime date (October 1, 2013).

When adding a new package, you can specify the payment method by using paymethod field.

  • If you know the creditcard_id, ach_id, or tokenized_id value you want to use for payment, just specify that field and value - you do not need to specify paymethod at all in this case.

  • To use any credit card the customer already has on file, just specify "paymethod": "crd".

  • To use any ACH/eCheck account the customer already has on file, just specify "paymethod": "ach".

  • To use any payment method available for this customer, just specify "paymethod": "any".

  • If you do not specify a payment method at all, ChargeOver will default to sending an invoice to the customer.

Optionally, when adding a new package, you can specify the payment cycle (how often the customer gets invoiced and/or charged for the subscription) by using the paycycle field. There are several payment cycles you can set a package to run on:


  • dly - Daily

  • 1wk - Every week

  • 2wk - Every other week

  • 116 - 1st and the 16th

  • 4wk - Every four weeks

  • 8wk - Every eight weeks

  • 30d - Every 30 days

  • mon - Monthly

  • 2mn - Every other month

  • 12w - Every twelve weeks

  • qtr - Quarterly

  • six - Every six months

  • yrl - Yearly

  • 2yr - Every 2 years

  • 3yr - Every 3 years

  • 4yr - Every 4 years

  • 5yr - Every 5 years

  • 10y - Every 10 years

If you do not specify a paycycle, the payment cycle for the subscription will set to the default payment cycle configured in your account's General Settings.

ChargeOver supports mixed payment cycle subscriptions, e.g. where part of the subscription is monthly, and part of it is yearly.

Each line item can have its own payment cycle, as defined by the paycycle attribute. If you do not define a payment cycle for the line, it defaults to the payment cycle set on the product/discount being used.

Important: Invoices are created using the paycycle of the subscription itself. Generally, your subscription payment cycle should be equal to the shortest payment cycle your lines use. Examples:

  • Subscription paycycle=mon (monthly), Line paycycle=yrl (yearly) - invoices are created monthly, but the line will only occur once per year.
  • Subscription paycycle=yrl (yearly), Line paycycle=mon (monthly) - invoices are created yearly, and each invoice will contain 12 lines (one for each month).

You can create prorated subscriptions which either generate a prorated invoice right away, or put the prorated charge on the next invoice.

The example to the right creates a new subscription, and generates a prorated invoice for the period March 12, to the end of March. The next invoice date will be April 1.

Request​

Body

    customer_id integer

    Customer ID #

    class_id integer

    Class ID #

    external_key string

    External key value

    nickname string

    Nickname for the subscription

    paymethod string

    Payment method for the subscription, one of: crd, inv, ach, tok

    creditcard_id integer

    Credit card ID # (if the subscription is paid by credit card)

    ach_id integer

    ACH ID # (if the subscription is paid by ACH)

    tokenized_id integer

    Tokenized ID # (if the subscription is paid by an external service token)

    admin_id integer

    Admin/worker ID #

    bill_addr1 string

    Billing address line 1

    bill_addr2 string

    Billing address line 2

    bill_addr3 string

    Billing address line 3

    bill_city string

    Billing address city

    bill_state string

    Billing address state

    bill_postcode string

    Billing address postal code

    bill_country string

    Billing address country

    bill_notes string

    (Deprecated)

    ship_addr1 string

    Shipping address line 1

    ship_addr2 string

    Shipping address line 2

    ship_addr3 string

    Shipping address line 3

    ship_city string

    Shipping address city

    ship_state string

    Shipping address state

    ship_postcode string

    Shipping address postal code

    ship_country string

    Shipping address country

    ship_notes string

    (Deprecated)

    holduntil_datetime string

    Date/time invoicing for this subscription is being delayed until

    terms_id integer

    Terms ID #

    paycycle string

    Payment cycle

    custom_1 string

    Custom field #1

    custom_2 string

    Custom field #2

    custom_3 string

    Custom field #3

    custom_4 string

    Custom field #4

    custom_5 string

    Custom field #5

    custom_6 string

    Custom field #6

    custom_7 string

    Custom field #7

    custom_8 string

    Custom field #8

    custom_9 string

    Custom field #9

    custom_10 string

    Custom field #10

    custom_11 string

    Custom field #11

    custom_12 string

    Custom field #12

    custom_13 string

    Custom field #13

    custom_14 string

    Custom field #14

    custom_15 string

    Custom field #15

    custom_16 string

    Custom field #16

    custom_17 string

    Custom field #17

    custom_18 string

    Custom field #18

    custom_19 string

    Custom field #19

    custom_20 string

    Custom field #20

    first_invoice_schedule_template_id integer

    Payment schedule to use for the first invoice generated

    recurring_invoice_schedule_template_id integer

    Payment schedule to use for subsequent generated invoices

    line_items array

    A list of line items for the subscription

    tags string[]

    A list of tags

Responses​

Object was created successfully

Schema

    code integer
    status string
    message stringnullable
    details objectnullable

    response

    object

    id integer
Loading...