Guides
GuidesAPI ReferenceNotificationsDiscussionsSupportStatus

Troubleshoot Backend REST APIs

API response takes too long

Symptoms

One or more REST API requests take significantly longer than expected to complete.

Cause

A high volume of API requests can increase response times. This commonly occurs when an application sends repeated requests in a loop or retry mechanism.

Resolution

Verify that your application is not sending unnecessary or duplicate requests. In particular:

  • Check for loops that repeatedly call the same endpoint.
  • Review any retry logic or batch processes that may generate excessive requests.
  • Reduce the request volume where possible.

If the issue persists after reviewing your implementation, contact Client Experience and provide details such as the affected endpoint, request timestamps, and example requests.

Related topics

Downgrade fails due to alignment error

Symptoms


Calling the Update Subscription Item endpoint returns the following error:

{
  "ResultMessage": "Alignment CUS price total must be >= 0"
}

Cause

The request sets AlignToCurrentInterval to true while decreasing the subscription item's quantity or price.

When AlignToCurrentInterval is enabled, the subscription change is applied immediately and the API calculates a prorated alignment charge. If the calculation results in a negative amount (for example, because the customer would be entitled to a partial refund), the request fails because the Subscription API does not support refunds.

Resolution

If the downgrade should take effect at the next renewal, set:

"AlignmentSettings": {
  "AlignToCurrentInterval": false,
  "ExtendInterval": false,
  "GetCustomerPricePreviewOnly": false
}

This schedules the downgrade for the next billing interval and avoids a negative alignment price.

Example

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": false
    },
    "GenerateMail": true,
    "ProductId": 123456,
    "Quantity": 4,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": false,
    "UpdateAction": "Downgrade"
  }'

Related topics

Subscription payment could not be processed

Symptoms

A subscription update succeeds, but the recurring payment cannot be processed.

Cause

Subscription updates and payment processing are handled independently. This allows subscription changes to be processed immediately while payment is handled separately.

Resolution

No additional API call is required.

If the payment fails:

  1. The customer receives an email with a link to update their payment information or select a different payment method.
  2. You receive a payment failure notification.
  3. After the customer updates their payment details, Cleverbridge automatically retries the payment.
  4. If the payment succeeds, Cleverbridge recalculates the next billing date and sends a payment confirmation notification.

Related topics

Negative alignment price

Symptoms

A subscription update request fails when AlignToCurrentInterval is set to true.

Cause

The requested change results in a negative prorated alignment amount. When this happens, the Subscription API rejects the request and no subscription changes are applied.

A negative alignment price can occur in the following situations:

  • The item price decreases while the quantity remains the same.
  • The item quantity decreases while the price remains the same.
  • Both the price and quantity decrease, resulting in a lower total amount than the current subscription.
  • An Align Subscriptions operation encounters an overpayment from a previous billing interval.

Resolution

Review the requested subscription change and determine whether it should take effect immediately.

If the change can wait until the next renewal, set:

"AlignmentSettings": {
  "AlignToCurrentInterval": false
}

This schedules the change for the next billing interval and avoids negative alignment calculations.

If the change must take effect immediately, modify the request so that the prorated alignment amount is not negative.

Related topics