Sign in

v1

latestOpenAPI 3.0.12026-07-242871595.3 MB
SUBSCRIPTIONS

Create a subscription under a plan

Creates a subscription under a plan, including details such as customer billing information, card-on-file, scheduled payment amount, start date, and payment intervals.

post/v1/plans/{planId}/subscriptions

Path parameters

planIdstring required

Universally unique identifier (UUID) of the plan with subscriptions.

Headers

X-Clover-Merchant-Idstring required

Clover merchant identifier (mId).

User-Agentstring required

Identifies the application, operating system, vendor, and/or version of the requesting user agent. Format: <application>/<version>

Request body

startDatestring date-time

Start date of the subscription plan in ISO-8601 format. For example, September 7, 2023 displays as 20230907 or with delimiters as 2023-09-07. Time displays in hours, minutes, and seconds, as 12:07:22.

collectionMethod'CHARGE_AUTOMATICALLY' | 'AUTHORIZE_AUTOMATICALLY' | 'SEND_INVOICE' required

Method of collecting the subscription. Values:

  • Charge_automatically
  • Authorize_automatically
  • Send_invoice
endDatestring date-time

End date of the subscription plan in ISO-8601 format. For example, September 7, 2023 displays as 20230907 or with delimiters as 2023-09-07. Time displays in hours, minutes, and seconds, as 12:07:22.

notestring

Additional information or note related to the subscription. If available, it overrides the plan's subscription.

tipAmountinteger

Tip amount. If available, it overrides the plan's amount.

amountinteger

Amount of the subscription. If available, it overrides the plan's amount.

activeboolean

Indicates whether the subscription is currently active. Values:

  • True
  • False
taxRateUuidsstring[]

Universally unique identifiers (UUIDs) of the tax rate. If available, it overrides the plan's subscription. Length: Maximum length of combined UUIDs is more than 255 characters.

customerIdstring uuid required

Customer identifier (ID).

Example request

{
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "note": "note",
  "amount": 6,
  "endDate": "2000-01-23T04:56:07.000Z",
  "tipAmount": 0,
  "customerId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  "softDescriptor": {
    "merchantContactInfo": "merchantContactInfo",
    "city": "city",
    "street": "street",
    "countryCode": "countryCode",
    "postalCode": "postalCode",
    "dbaName": "dbaName",
    "region": "region"
  },
  "active": true,
  "startDate": "2000-01-23T04:56:07.000Z",
  "level2": {
    "vatTaxRate": 9,
    "freightAmount": 2,
    "pcOrderNumber": "pcOrderNumber",
    "destinationCountryCode": "destinationCountryCode",
    "discountAmount": 3,
    "purchaseIdentifier": "purchaseIdentifier",
    "shipFromPostalCode": "shipFromPostalCode",
    "taxIndicator": "UNKNOWN",
    "destinationPostalCode": "destinationPostalCode",
    "merchantTaxId": "merchantTaxId",
    "vatTaxAmount": 7,
    "taxAmount": 2,
    "dutyAmount": 4,
    "productDescription": "productDescription"
  },
  "taxRateUuids": [
    "taxRateUuids",
    "taxRateUuids"
  ]
}

Response

Successful response. Subscription is created in a plan.

objectstring

Subscription object.

idstring UUID

Subscription identifier.

customerUuidstring uuid

Customer universally unique identifier (UUID).

collectionMethod'CHARGE_AUTOMATICALLY' | 'AUTHORIZE_AUTOMATICALLY' | 'SEND_INVOICE'

Method for collecting payment. Currently, charge_automatically is the only method allowed.

merchantIdstring uuid

Merchant identifier (ID) who applied for the subscription plan.

activeboolean

Indicates whether the merchant business is active or not. Values:

  • True
  • False
tipAmountinteger

Tip amount.

amountinteger

Amount of subscription.

startDatestring date-time

Start date of the subscription plan in ISO-8601 format. For example, September 7, 2019 displays as 20190907 or expressed with delimiters as 2019-09-07. Time displays in hours, minutes, and seconds, as 12:07:22.

endDatestring date-time

End date of the subscription plan in ISO-8601 format. For example, September 7, 2019 displays as 20190907 or expressed with delimiters as 2019-09-07. Time displays in hours, minutes, and seconds, as 12:07:22.

notestring

Subscription note, if any.

lastRunDatestring date-time

Last run date of subscription.

createdTimestring date-time

Time when subscription was created.

modifiedTimestring date-time

Time when subscription was modified.

deletedTimestring date-time

Time when subscription was deleted.

taxRateUuidsstring[]

Tax rate universally unique identifier (UUID) for the plan.

Example response

{
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "note": "note",
  "modifiedTime": "2000-01-23T04:56:07.000Z",
  "amount": 5,
  "tipAmount": 5,
  "endDate": "2000-01-23T04:56:07.000Z",
  "active": true,
  "softDescriptor": {
    "merchantContactInfo": "merchantContactInfo",
    "city": "city",
    "street": "street",
    "countryCode": "countryCode",
    "postalCode": "postalCode",
    "dbaName": "dbaName",
    "region": "region"
  },
  "lastRunDate": "2000-01-23T04:56:07.000Z",
  "taxRateUuids": [
    "taxRateUuids",
    "taxRateUuids"
  ],
  "customerUuid": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  "merchantId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  "createdTime": "2000-01-23T04:56:07.000Z",
  "id": "id",
  "deletedTime": "2000-01-23T04:56:07.000Z",
  "plan": {
    "note": "note",
    "modifiedTime": "2000-01-23T04:56:07.000Z",
    "amount": 6,
    "tipAmount": 0,
    "active": true,
    "uuid": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "taxRateUuids": [
      "taxRateUuids",
      "taxRateUuids"
    ],
    "productUuid": "productUuid",
    "merchantId": "merchantId",
    "intervalCount": 1,
    "name": "name",
    "createdTime": "2000-01-23T04:56:07.000Z",
    "interval": "DAY",
    "id": "id",
    "deletedTime": "2000-01-23T04:56:07.000Z"
  },
  "startDate": "2000-01-23T04:56:07.000Z",
  "object": "object",
  "level2": {
    "vatTaxRate": 9,
    "freightAmount": 2,
    "pcOrderNumber": "pcOrderNumber",
    "destinationCountryCode": "destinationCountryCode",
    "discountAmount": 3,
    "purchaseIdentifier": "purchaseIdentifier",
    "shipFromPostalCode": "shipFromPostalCode",
    "taxIndicator": "UNKNOWN",
    "destinationPostalCode": "destinationPostalCode",
    "merchantTaxId": "merchantTaxId",
    "vatTaxAmount": 7,
    "taxAmount": 2,
    "dutyAmount": 4,
    "productDescription": "productDescription"
  }
}