Get All Billing Cycles

GET /subscriptions/:subscriptionId/billing-cycles

Returns a list of all Billing Cycles linked to a subscription with pagination. The Billing Cycles returned also show the list of the transactions executions linked to each cycle including the retries.

info

The request must provide the following header: x-api-key: {merchantKey}

Request

Path Parameters

subscriptionId stringrequired

Unique Identifier of the created Subscription. Format: Subscription + - + <UUID>

Example: Subscription-4903f0f3-d718-404b-a675-167eacfabe12

Query Parameters

page integer

Number of the page for which the data is to be returned.

pageSize integer

Number of the records to display per page.

Header Parameters

Content-Type stringrequired

Must be application/json

Accept-Language stringrequired

Must be be en-US

Origin stringrequired

The origin of the request

User-Agent stringrequired

The client making the request

x-api-key stringrequired

x-api-key: {merchantKey}

Responses

Successful response

application/json

Schema
Example (auto)
Example

Schema

pageinteger

Number of the page for which the data is returned.

pageSizeinteger

Number of the records displayed per page.

countinteger

Number of total records (Billing Cycles) returned for the made search/request.

totalPagesinteger

Number of pages returned for the made search/request.

data object[]

Array [

idstringrequired

Unique Identifier of the Billing Cycle. Format: BillingCycle + - + <UUID>

Example: BillingCycle-90d9e9bc-fd51-4698-b254-b8a57d3a72d9

createdAtstring<date-time>required

Timestamp of when the Billing Cycle was created.

Example: 2021-02-11T15:00:44.718Z

updatedAtstring<date-time>required

Timestamp of when the Billing Cycle was last updated.

Example: 2021-02-11T15:00:44.718Z

paidAtstring<date-time>nullable

Timestamp of when the Billing Cycle was paid, if applicable.

Example: 2021-02-11T15:00:44.718Z

billingDatestring<date>required

The date of billing.

Example: 2021-03-31

billingPeriodStartstring<date>required

The start date of the billing period.

Example: 2021-03-01

billingPeriodEndstring<date>required

The end date of the billing period.

Example: 2021-03-31

statusstringrequired

Status of the billing cycle. Default: PENDING.

Possible values: [PENDING, CREATED, AUTHORIZATION PENDING, AUTHORIZATION COMPLETED, FAILED, CAPTURE PENDING, EXPIRED, CAPTURED, ERROR]

Example: PENDING

amountnumber<decimal>required

Amount of the transaction.

Example: 10

currencystringrequired

Currency code of the transaction. Format ISO 4217.

Possible values: >= 3 characters and <= 3 characters

Example: EUR

shortCardNumberstringrequired

Masked PAN for card, masked IBAN for SEPA, or masked email for PayPal.

Possible values: <= 255 characters

Example: 520000****0072

billingAgreementNamestringrequired

Display name of the payment option which has been stored.

Possible values: <= 255 characters

Example: Mastercard

billingAgreementIdstring

ID of the associated billing agreement.

Example: BillingAgreement-df9cae2e-e424-490f-8bcb-ce52e81e6781

billingAgreementCarrierNumberstring

Carrier number of the associated billing agreement.

Example: 12541****1235

]

{
  "page": 0,
  "pageSize": 0,
  "count": 0,
  "totalPages": 0,
  "data": [
    {
      "id": "BillingCycle-90d9e9bc-fd51-4698-b254-b8a57d3a72d9",
      "createdAt": "2021-02-11T15:00:44.718Z",
      "updatedAt": "2021-02-11T15:00:44.718Z",
      "paidAt": "2021-02-11T15:00:44.718Z",
      "billingDate": "2021-03-31",
      "billingPeriodStart": "2021-03-01",
      "billingPeriodEnd": "2021-03-31",
      "status": "Captured",
      "amount": 10,
      "currency": "EUR",
      "shortCardNumber": "520000****0072",
      "billingAgreementName": "Mastercard",
      "billingAgreementId": "BillingAgreement-df9cae2e-e424-490f-8bcb-ce52e81e6781"
    }
  ]
}

{
  "page": 0,
  "pageSize": 2,
  "count": 2,
  "totalPages": 1,
  "data": [
    {
      "id": "BillingCycle-d43eed32-e035-4eb4-9e1b-94c54a00f60a",
      "createdAt": "2021-06-18T06:12:39.33Z",
      "updatedAt": "2021-06-18T06:16:36.16Z",
      "paidАt": "2021-06-18T06:16:34.69Z",
      "billingDate": "2021-06-18",
      "billingPeriodStart": "2021-06-17",
      "billingPeriodEnd": "2021-06-18",
      "status": "captured",
      "amount": 10,
      "currency": "EUR",
      "shortCardNum": "520000****0072",
      "billingAgreementId": "BillingAgreement-df9cae2e-e424-490f-8bcb-ce52e81e6781"
    },
    {
      "id": "BillingCycle-44401c1b-c762-42dd-81bc-fd1fbad54af2",
      "createdAt": "2021-06-17T12:42:41.00Z",
      "updatedAt": "2021-06-17T12:46:34.75Z",
      "paidАt": "2021-06-17T12:46:33.40Z",
      "billingDate": "2021-06-17",
      "billingPeriodStart": "2021-06-17",
      "billingPeriodEnd": "2021-06-18",
      "status": "captured",
      "amount": 10,
      "currency": "EUR",
      "shortCardNum": "520000****0072",
      "billingAgreementId": "BillingAgreement-df9cae2e-e424-490f-8bcb-ce52e81e6781"
    }
  ]
}

Bad Request

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]

Array [

messagestring

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

codestring

A pre-defined code from the list of error codes.

propertystring

The property from the request object which the error is linked to.

context object

A json object containing a list of predefined properties which are filled based on the error.

typestring

minimumnumber

maximumnumber

maxLengthinteger

allowedValuesstring[]

]

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Value out of bounds. Value must be between 1 and 100",
      "code": "value_out_of_bounds",
      "property": "someField",
      "context": {
        "minimum": 1,
        "maximum": 100
      }
    }
  ]
}

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]

Array [

messagestring

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

codestring

A pre-defined code from the list of error codes.

propertystring

The property from the request object which the error is linked to.

context object

A json object containing a list of predefined properties which are filled based on the error.

typestring

minimumnumber

maximumnumber

maxLengthinteger

allowedValuesstring[]

]

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You are not authenticated to perform this request.",
      "code": "unauthorized"
    }
  ]
}

Forbidden

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]

Array [

messagestring

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

codestring

A pre-defined code from the list of error codes.

propertystring

The property from the request object which the error is linked to.

context object

A json object containing a list of predefined properties which are filled based on the error.

typestring

minimumnumber

maximumnumber

maxLengthinteger

allowedValuesstring[]

]

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You do not have permissions to perform this request.",
      "code": "forbidden"
    }
  ]
}

Not Found

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]

Array [

messagestring

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

codestring

A pre-defined code from the list of error codes.

propertystring

The property from the request object which the error is linked to.

context object

A json object containing a list of predefined properties which are filled based on the error.

typestring

minimumnumber

maximumnumber

maxLengthinteger

allowedValuesstring[]

]

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Resource not found.",
      "code": "not_found"
    }
  ]
}

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]

Array [

messagestring

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

codestring

A pre-defined code from the list of error codes.

propertystring

The property from the request object which the error is linked to.

context object

A json object containing a list of predefined properties which are filled based on the error.

typestring

minimumnumber

maximumnumber

maxLengthinteger

allowedValuesstring[]

]

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Internal server error."
    }
  ]
}

Get All Billing Cycles

/subscriptions/:subscriptionId/billing-cycles

Request​

Path Parameters

Query Parameters

Header Parameters

Responses​

Request

Responses