Skip to main content

Portal for Changing Subscription Plans

POST 
/truckers/payment/changePlans

Generate a URL to access the Stripe billing portal and manage the current subscription.

Technical Flow:

  1. Verify user authentication
  2. Get the company associated with the user
  3. Validate that an active subscription exists
  4. Verify that the company has an associated Stripe account
  5. Create a session in the Stripe billing portal
  6. Return the URL to redirect the user

Validations:

  • User must be authenticated (valid JWT)
  • User must belong to a valid company
  • The company must have an associated Stripe account
  • There must be an active, non-expired subscription
  • The returnUrl parameter is mandatory

Required Parameters:

  • returnUrl: URL to which Stripe will redirect after managing the subscription

Request Example:

{
  returnUrl: https://app.cargoffer.com/payment/success
}

Successful Response Example:

{
  url: https://billing.stripe.com/session/xyz123
}

Error Cases:

  • 400 Bad Request:
    • Missing returnUrl parameter
    • Subscription not active or expired
  • 401 Unauthorized:
    • Invalid JWT token
    • User has no associated company
    • No Stripe account configured
  • 500 Internal Server Error: Error connecting to Stripe

Frontend Usage Example:

// Frontend: Access the billing portal
const accessBillingPortal = async (returnUrl) => {
  try {
    const response = await axios.post(
      '/truckers/payment/changePlans',
      { returnUrl },
      { headers: { Authorization: `Bearer ${token}` } }
    );
    
    if (response.data.url) {
      window.location.href = response.data.url; // Redirect to Stripe
    }
  } catch (error) {
    handleError(error);
  }
};

Important Notes:

  • Allows changing/canceling the current subscription
  • Shows payment history and invoices
  • Requires an active subscription to function
  • The generated URL has limited validity (30 min)

Request​

Responses​

Stripe Billing Portal URL