v1

latestOpenAPI 3.0.02026-07-2671142187.3 KB

Subscriptions

Create subscriptions

Create one or more subscriptions to your payment plans.

post/subscriptions

Headers

api-tokenstring required

Your API access token for authentication and access to the Helcim API

idempotency-keystring required

A unique 25 character alphanumeric key to ensure the request is idempotent. Requests containing keys used in previously successful requests will be rejected.

Request body

Example request

{
  "subscriptions": [
    {
      "dateActivated": "2024-02-01",
      "paymentPlanId": 5878,
      "customerCode": "CST1200",
      "useCustomSetupAmount": true,
      "setupAmount": 5,
      "recurringAmount": 15.99,
      "withFreeTrialPeriod": true,
      "paymentMethod": "card",
      "addOns": [
        {
          "addOnId": 123,
          "quantity": 3
        },
        {
          "addOnId": 455
        }
      ]
    }
  ]
}

Response

Successful subscription creation. The response body contains the data representation of all newly created subscriptions, the first payment, and applied active add-ons. If any created subscriptions were immediately billed the returned payment will indicate whether the billing was approved or declined. Only active add-ons will be present in the response, one time add-ons that were immediately billed will not be present.

Example response

{
  "data": [
    {
      "id": 123456,
      "dateCreated": "2024-01-01 12:30:45",
      "dateUpdated": "1970-01-01 00:00:00",
      "dateActivated": "2024-02-01",
      "dateBilling": "2024-02-07",
      "status": "active",
      "paymentPlanId": 5878,
      "customerCode": "CST1200",
      "timesBilled": 1,
      "setupAmount": 5,
      "recurringAmount": 15.99,
      "freeTrialPeriod": 7,
      "hasFailedPayments": "false",
      "addOnIds": [
        123,
        455
      ],
      "payments": [
        {
          "id": 49978,
          "setupAmount": 0,
          "recurringAmount": 0,
          "addOnAmount": 0,
          "amount": 15.99,
          "taxAmount": 0,
          "status": "waiting",
          "dateDue": "2024-02-07 00:00:00",
          "dateProcessed": "1970-01-01 00:00:00",
          "paymentNumber": 1,
          "numberOfRetries": 0
        }
      ],
      "subscriptionAddOns": [
        {
          "addOnId": 123,
          "name": "My first add-on",
          "description": "",
          "amount": 3.5,
          "firstProcessedNumber": 0,
          "lastProcessedNumber": 0,
          "isActive": "true",
          "frequency": "recurring",
          "quantity": 3
        },
        {
          "addOnId": 455,
          "name": "One time add-on",
          "description": "",
          "amount": 5,
          "firstProcessedNumber": 0,
          "lastProcessedNumber": 0,
          "isActive": "true",
          "frequency": "one_time",
          "quantity": 1
        }
      ]
    }
  ]
}