Connect Session Intents
This page provides an overview of the various intents that can be used with Connect Sessions and the destinations to which users will be redirected for each.
cancelSubscription
This will open Connect on the subscription settings page. However, it does not automatically cancel the subscription. User action is still needed. Upon successful cancellation,
users will be redirected back to callbackUrl
if provided.
The request expects a cancelSubscription
object that defines the subscription
to cancel:
Creating a Connect Session with cancelSubscription intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "cancelSubscription",
"cancelSubscription": {
"subscription": "sub_0U32VAxJ0Z7P8Y40mBAnOP9LPhEr"
}
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
Note: Ensure the subscription is cancelable (i.e., it has no endedAt
set and is of type recurring
) before creating a Connect Session, as this is not validated for you. If you redirect the user to a non-cancelable subscription, Connect will still open the subscription details view, but the cancel button will not be present. This might be confusing to users.
changeSubscription
Upon opening Connect, the user will be directed to the 'Add Data' page where they have the option to select a different plan or purchase an add-on. Upon successful purchase, if a callbackUrl
was provided, users will be redirected back to it when clicking the Continue button.
The request expects a changeSubscription
object that defines the subscription
to change.
Creating a Connect Session with changeSubscription intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "changeSubscription",
"changeSubscription": {
"subscription": "sub_0U32VAxJ0Z7P8Y40mBAnOP9LPhEr"
}
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
Note: Please confirm that the subscription actually offers alternative plans and/or purchasable add-ons. Redirecting the user to a subscription without any options for changes or add-ons will cause Connect to open in the change plan view without displaying any alternative plans or add-ons. This might confuse users.
checkoutAddon
This will open Connect on the checkout page for an add-on, with the specified add-on for the given subscription already in the cart. The user will still need to manually initiate the payment. Upon successful purchase, if a callbackUrl
was provided, users will be redirected back to it when clicking the Continue button.
The request expects a checkoutAddon
object that defines the subscription
for which to purchase the add-ons as well as an array of addons
to purchase.
Creating a Connect Session with checkoutAddon intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "checkoutAddon",
"checkoutAddon": {
"subscription": "sub_0U32VAxJ0Z7P8Y40mBAnOP9LPhEr",
"addons": ["add_0U32Zonj0Z7P8Y0kDmHNLzgaevse"]
}
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
checkoutNewSubscription
This will open Connect in the checkout flow with a subscription already selected. The user's exact entry point depends on the combination of the selected plan and the provided payload. For instance, if you pass a SIM ID in the payload, Connect will skip the SIM selection screen. Upon successful purchase, if a callbackUrl
was provided, users will be redirected back to it when clicking the Continue button.
The request expects a checkoutNewSubscription
object that can define the plan
to buy a subscription for, a sim
and device
as well as an array of addons
to purchase with the subscription.
Creating a Connect Session with checkoutNewSubscription intent
bash
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "checkoutNewSubscription",
"checkoutNewSubscription": {
"plan": "pln_0U32ZjA60Z7P8Y5vLtmvXaIMEiPr",
"sim": "sim_0U32TCTS0Z7P8Y4gBoN1duXbdi2m"
}
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
Note:
- In contrast to the create subscription endpoint, it is currently not possible to pass in
auto
as a value for thesim
field to default to a new eSIM. The field also does not default toauto
, so if you leave it out, Connect will open on the SIM selection page. - Please make sure to pass a plan that is
active
to make sure the user can progress with the checkout in connect.
completePorting
Connect will open on the complete porting page for a subscription. If the user has previously started the porting process, Connect will resume from where the user left off. Upon completing all required porting steps, users will be redirected back to callbackUrl
if provided.
The request expects a completePorting
object that defines the subscription
for which to complete a porting.
Creating a Connect Session with completePorting intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "completePorting",
"completePorting": {
"subscription": "sub_0U32VAxJ0Z7P8Y40mBAnOP9LPhEr"
}
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
Note: Please confirm that the subscription has a pending porting associated with it before creating a Connect Session. This is not checked during session creation. Redirecting the user to a subscription without a pending porting will open Connect in the subscription overview and might confuse users.
confirmPayment
Will open Connect on the payment confirmation page. Upon successful confirmation, users will be redirected back to callbackUrl
if provided.
The request expects a confirmPayment
object that defines the payment
to be confirmed.
Creating a Connect Session with confirmPayment intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "confirmPayment",
"confirmPayment": {
"payment": "pay_19XU2VA2J0Z7P8Y40mBAnOP9L1PAr"
}
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
Note: Only payments with a status of requiresConfirmation
are allowed as inputs to this intent.
resumeSubscription
This will open Connect on the subscriptions settings page. However, it will not automatically renew the subscription; user action is still required. Upon resumption, users will be redirected back to callbackUrl
if provided.
The request expects a resumeSubscription
object that defines the subscription
to be resumed.
Creating a Connect Session with resumeSubscription intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "resumeSubscription",
"resumeSubscription": {
"subscription": "sub_0U32VAxJ0Z7P8Y40mBAnOP9LPhEr"
}
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
Note: Please ensure that the subscription is resumable (i.e., it has an endedAt
set and is of type recurring
). Connect Sessions do not perform this validation. Redirecting a user to a non-renewable subscription will cause Connect to open in the subscription details view without the possibility to resume the subscription. This might confuse users.
updatePaymentMethod
Will open Connect on the payment methods page. Upon successful update, users will be redirected back to callbackUrl
if provided.
Creating a Connect Session with updatePaymentMethod intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "updatePaymentMethod"
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
updateUserAddress
Will open Connect on the edit address page. Upon successful update, users will be redirected back to callbackUrl
if provided.
Creating a Connect Session with updateUserAddress intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "updateUserAddress"
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
updateUserFullName
Will open Connect on the edit user name page. Upon successful update, users will be redirected back to callbackUrl
if provided.
Creating a Connect Session with updateUserFullName intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "updateUserFullName"
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
viewEsimInstallation
Will open Connect on the eSIM Installation Guides page. Upon successful installation, if a callbackUrl
was provided, users will be redirected back to it when clicking the Done
button.
The request expects a viewEsimInstallation
object that defines the subscription
for which to show the installation guides.
Creating a Connect Session with viewEsimInstallation intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "viewEsimInstallation",
"viewEsimInstallation": {
"subscription": "sub_0U32VAxJ0Z7P8Y40mBAnOP9LPhEr"
}
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
viewSubscription
Will open Connect on the subscription details page.
The request expects a resumeSubscription
object that defines the subscription
for which to display the details.
Creating a Connect Session with viewSubscription intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "viewSubscription",
"viewSubscription": {
"subscription": "sub_0U32VAxJ0Z7P8Y40mBAnOP9LPhEr"
}
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
viewSubscriptions
Will open Connect on the subscriptions overview page.
Creating a Connect Session with viewSubscriptions intent
$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--data '{
"callbackUrl": "https://example.com",
"intent": {
"type": "viewSubscriptions"
},
"user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
}'
Where to go from here
- Read the Connect Sessions API Documentation
- Read about Disabling Hosted Connect Login
- Reach out to support@gigs.com for assistance