Home > API > Clients > Start subscription

Start subscription

Create a new or update an existing subscription.

PATH:

/v1/clients/{clientId}/subscriptions/{subscriptionId}

PATH PARAMETERS:

clientId
required

integer

Your assigned ClientId.
subscriptionId
required

string

Id of the subscription to retrieve.

HYPERMEDIA CONTROLS:

REQUEST BODY SCHEMA:

customerNumber

string <= 100 characters

Id of the customer to assign this subscription to.
subscriptionProductId

string <= 100 characters

Id of the subscription product.
billingDayOffset

integer

The billing day offset. Use this to adjust the billing day.
metadata

array of metadata

Optional. A list of key-value pairs.
key

string <= 30 characters

The key of the metadata item.
value

string <= 255 characters

The value of the metadata item.
activeFrom

string date

The date from which date this subscription is active.

RESPONSES:

200 Success, subscription updated.

RESPONSE SCHEMA:

id

string

Id of the subscription.
status

string

Enum: NOT_STARTED ACTIVE CLOSING CLOSED PAUSED

no description in swagger file
createdAt

string date-time

When this subscription was created.
updatedAt

string date-time

When this subscription was updated.
customerNumber

string <= 100 characters

Id of the customer the subscription is assigned to.
subscriptionProductId

string <= 100 characters

Id of the subscription product used in this subscription.
metadata

array of metadata

no description in swagger file
Array () [
key

string <= 30 characters

The key of the metadata item.
value

string <= 255 characters

The value of the metadata item.

]
active

active object

Timespan of when the subscription is active.
from

string date

no description in swagger file
until

string date

no description in swagger file
closeDetails
required

object of closeDetails

Details about how the subscription has been canceled. Only visible when a subscription has been canceled.
canceledByClient

boolean

Whether the subscription was canceled by the client.
canceledByBillingPartner

boolean

Whether the subscription was canceled by the billing partner.
terminatedByClient

boolean

Whether the subscription was terminated by the client.
billingDetails
required

object of billingDetails

Billing details.
nextBillingDate

string date

The next billing date of this subscription.
billingDayOffset

integer int32

The billing day offset. Use this to adjust the billing day.
currentPeriod
required

object of currentPeriod

Timespan of the current period of the subscription.
start

string date

First day of the period.
end

string date

Last day of the period.
commitment
required

object of commitment

Commitment information. Only set if the subscription has commitment agreement.
end

string date

Last date of the commitment.
remainingPeriods

integer

Remaining periods in the commitment.
_links

array of _links

List of hypermedia links related to this resource.
Array () [
method

string

HTTP Method.
href

string

Link to the resource.
rel

string

The relation between the current and target resource.

]
201 Success, subscription created.

RESPONSE SCHEMA:

id

string

Id of the subscription.
status

string

Enum: NOT_STARTED ACTIVE CLOSING CLOSED PAUSED

no description in swagger file
createdAt

string date-time

When this subscription was created.
updatedAt

string date-time

When this subscription was updated.
customerNumber

string <= 100 characters

Id of the customer the subscription is assigned to.
subscriptionProductId

string <= 100 characters

Id of the subscription product used in this subscription.
metadata

array of metadata

no description in swagger file
Array () [
key

string <= 30 characters

The key of the metadata item.
value

string <= 255 characters

The value of the metadata item.

]
active

active object

Timespan of when the subscription is active.
from

string date

no description in swagger file
until

string date

no description in swagger file
closeDetails
required

object of closeDetails

Details about how the subscription has been canceled. Only visible when a subscription has been canceled.
canceledByClient

boolean

Whether the subscription was canceled by the client.
canceledByBillingPartner

boolean

Whether the subscription was canceled by the billing partner.
terminatedByClient

boolean

Whether the subscription was terminated by the client.
billingDetails
required

object of billingDetails

Billing details.
nextBillingDate

string date

The next billing date of this subscription.
billingDayOffset

integer int32

The billing day offset. Use this to adjust the billing day.
currentPeriod
required

object of currentPeriod

Timespan of the current period of the subscription.
start

string date

First day of the period.
end

string date

Last day of the period.
commitment
required

object of commitment

Commitment information. Only set if the subscription has commitment agreement.
end

string date

Last date of the commitment.
remainingPeriods

integer

Remaining periods in the commitment.
_links

array of _links

List of hypermedia links related to this resource.
Array () [
method

string

HTTP Method.
href

string

Link to the resource.
rel

string

The relation between the current and target resource.

]
202 Success, subscription creation initiated. Further action is required.

RESPONSE SCHEMA:

id

string

Id of the subscription.
sessionId

string

Identifies the SCA session.
_links

array of _links

List of hypermedia links related to this resource.
Array () [
method

string

HTTP Method.
href

string

Link to the resource.
rel

string

The relation between the current and target resource.

]
400 Bad request.

RESPONSE SCHEMA:

undefined
401 Missing or invalid "Authorization" header.

RESPONSE SCHEMA:

type

string

The type of error that is carried within this response. The value of this type is an URI that can be dereferenced for a human-readable explanation of the error type.
category

string

Enum: BUSINESS_ERROR TECHNICAL_ERROR

Category of the error, used primarily to determine whether the same request should be retried or not. Possible values:

  • BUSINESS_ERROR - A business error occured. This request should not be retried without modification
  • TECHNICAL_ERROR - A temporary, technical error occurred. the request should be retried after a back-off period.
title

string

A short, human-readable summary of the problem.
message

string

A short, human-readable summary of the problem. Identical to title.
403 Lacking permissions.

RESPONSE SCHEMA:

type

string

The type of error that is carried within this response. The value of this type is an URI that can be dereferenced for a human-readable explanation of the error type.
category

string

Enum: BUSINESS_ERROR TECHNICAL_ERROR

Category of the error, used primarily to determine whether the same request should be retried or not. Possible values:

  • BUSINESS_ERROR - A business error occured. This request should not be retried without modification
  • TECHNICAL_ERROR - A temporary, technical error occurred. the request should be retried after a back-off period.
title

string

A short, human-readable summary of the problem.
message

string

A short, human-readable summary of the problem. Identical to title.
500 Unexpected internal server error.

RESPONSE SCHEMA:

type

string

The type of error that is carried within this response. The value of this type is an URI that can be dereferenced for a human-readable explanation of the error type.
category

string

Enum: BUSINESS_ERROR TECHNICAL_ERROR

Category of the error, used primarily to determine whether the same request should be retried or not. Possible values:

  • BUSINESS_ERROR - A business error occured. This request should not be retried without modification
  • TECHNICAL_ERROR - A temporary, technical error occurred. the request should be retried after a back-off period.
title

string

A short, human-readable summary of the problem.
message

string

A short, human-readable summary of the problem. Identical to title.

Path

put

/v1/clients/{clientId}/subscriptions/{subscriptionId}

Request samples

  • {
    • "customerNumber": "string",
    • "subscriptionProductId": "string",
    • "billingDayOffset": 1,
    • "metadata": [ ...
      • {
        • "key": "string",
        • "value": "string"
        }
      ],
    • "activeFrom": "string"
  • }

Response samples

200201202400401403500
  • {
    • "customerNumber": "string",
    • "subscriptionProductId": "string",
    • "metadata": [ ...
      • {
        • "key": "string",
        • "value": "string"
        }
      ],
    • "active": { ...
      • "from": "string",
      • "until": "string"
      },
    • "closeDetails": X,
    • "billingDetails": X,
    • "currentPeriod": X,
    • "commitment": X,
    • "_links": [ ...
      • {
        • "method": "string",
        • "href": "string",
        • "rel": "string",
        • "target": X
        }
      ]
    }
  • {
    • "customerNumber": "string",
    • "subscriptionProductId": "string",
    • "metadata": [ ...
      • {
        • "key": "string",
        • "value": "string"
        }
      ],
    • "active": { ...
      • "from": "string",
      • "until": "string"
      },
    • "closeDetails": X,
    • "billingDetails": X,
    • "currentPeriod": X,
    • "commitment": X,
    • "_links": [ ...
      • {
        • "method": "string",
        • "href": "string",
        • "rel": "string",
        • "target": X
        }
      ]
    }
  • {
    • "id": "string",
    • "sessionId": "string",
    • "_links": [ ...
      • {
        • "method": "string",
        • "href": "string",
        • "rel": "string",
        • "target": X
        }
      ]
    }
undefined
  • {
    • "type": "string",
    • "category": "string",
    • "title": "string",
    • "message": "string"
    }
  • {
    • "type": "string",
    • "category": "string",
    • "title": "string",
    • "message": "string"
    }
  • {
    • "type": "string",
    • "category": "string",
    • "title": "string",
    • "message": "string"
    }