Set up app free trial period in billing using trialdays parameter

[VisionLab]

Hello,

On shopify.dev I red about the possibility to offer a free trial period to merchants using billing APIs.

Offer free trials with the Billing API (shopify.dev)

I'm developing an app based on php using Shopify Cli 3.0 and I want to offer a 30 days period of a free trial.

In the shopify.php config file of the app's template, I see I can define some billing parameters which I imagine are related to mutation parameters seen in the documentation linked above.

    "billing" => [
        "required" => true,

        // Example set of values to create a charge for $5 one time
        "chargeName" => "Example App Recurrent Billing",
        "amount" => 5.0,
        "currencyCode" => "USD", // Currently only supports USD
        "interval" => EnsureBilling::INTERVAL_EVERY_30_DAYS,
    ],

Unfortunately between these parameters in shopify.php i can't find the "trialDays". Looking at the EnsureBilling class code, i can't see any usage of that parameter in its scope.

    private static function requestRecurringPayment(Session $session, array $config, string $returnUrl): array
    {
        return self::queryOrException(
            $session,
            [
                "query" => self::RECURRING_PURCHASE_MUTATION,
                "variables" => [
                    "name" => $config["chargeName"],
                    "lineItems" => [
                        "plan" => [
                            "appRecurringPricingDetails" => [
                                "interval" => $config["interval"],
                                "price" => ["amount" => $config["amount"], "currencyCode" => $config["currencyCode"]],
                            ],
                        ],
                    ],
                    "returnUrl" => $returnUrl,
                    "test" => !self::isProd(),
                ],
            ]
        );
    }

How can I set up a free trial using the methods already available in the php app template?
Especially using shopify.php configurations and EnsureBilling?

Thank you!

[ShopifyDevSup]

Hi @VisionLab 👋

The inputs on the `appSubscriptionCreate` mutation would be formatted as follows:

{
    "name": "visionlab charge",
    "trialDays": 7,
    "returnUrl": "https://shopify.dev",
    "lineItems": [{
        "plan": {
            "appRecurringPricingDetails": {
                "interval": "EVERY_30_DAYS",
                "price": {
                    "amount": "100",
                    "currencyCode": "USD"
                }
            }
        }
    }]
}

Extrapolating to your php snippet, the below may be a good place to start:

private static function requestRecurringPayment(Session $session, array $config, string $returnUrl): array
{
    return self::queryOrException(
        $session,
        [
            "query" => self::RECURRING_PURCHASE_MUTATION,
            "variables" => [
                "trialDays" => 7, <!-- add this line -->
                "name" => $config["chargeName"],
                ...
                

If you run into any other issues, you can also submit an issue directly in the public repo here. 

Hope that helps!

[VisionLab]

Hi @ShopifyDevSup ,

Thank you for your answer.
My main doubt is:

Why the class EnsureBilling does not support the "trialDays" parameter if the underline mutation does?
And so, is it "Okay" to edit EnsureBilling's function "requestRecurringPayment" to make it does so?
Or since that class is part of Shopify's Libs i will have problems down the road with future updates?

Thank you!

[ShopifyDevSup]

I'd recommend posting any PHP library specific questions in the public repo here directly for more visibility amongst devs actively using the PHP library.