# Managing subscriptions

The Straal API allows creating, modifying or cancelling a subscription. To better understand how to manage a subscription, see two sample scenarios below. For technical details, such as what to include in the API request, see APIref: Subscriptions(opens new window) .

Use case – create a subscription with a trial

To better understand how to manage a subscription, consider the following example. This scenario fits an online service provider, such as music or video streaming sites. A new customer decides to subscribe to your service for a monthly fee of $9.99. As a newcomer, they get a free 30-day trial.

To add a new subscription, there needs to be a plan created beforehand. Plan defines how often and for what amount will you charge the customer. To learn how to create a plan, see "Plans" above.

Once there is a plan created, you can create a subscription. A subscription needs to be connected to customer and card objects, which you need to create beforehand. See APIref: Create a customer(opens new window) and APIref: Create a card using CryptKey(opens new window) ).

To do so, you will need:

  • your plan's ID generated at its creation (plan_id)
  • credit or debit card details
  • the customer's email address
  • (optionally) your unique reference for this customer

After you create a customer and link him to a card you can create the subscription. A request body for creating a subscription (endpoint: https://api.straal.com/v1/cards/:card_id/subscriptions) could look like this:

{
  "plan_id": "mcn15j2hwhq4f",
}

The response will contain information about newly created subscription. For details, see APIref: Create a subscription(opens new window) .

If you wish to check the details of your new subscription later, you can do so using its ID (see: APIref: Get a subscription(opens new window) ).

Use case – cancel a subscription

You own a chain of gyms and fitness clubs. One of your customers, Ms. Cortes is relocating to another country and, sadly, has to cancel her membership. You can cancel her monthly subscription using the Straal API.

Note:

  • If the customer changes her mind later, you can't restore a cancelled subscription. You'll have to create a new one instead.
  • When a subscription is cancelled, it ends after the current billing period is over.

To cancel a subscription, you'll need the following:

  • your API Key with the permission v1.subscriptions.cancel
  • subscription ID

To cancel a subscription, you send a POST request to https://api.straal.com/v1/subscriptions/:id/cancel where :id is the ID of the subscription you wish cancel. In the body of the request, you send an empty JSON: {}, optionally containing extra-data:.

You can see a sample response in APIref: Cancel a subscription(opens new window) .