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:

$ 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.

$ 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.

$ 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.

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 the sim field to default to a new eSIM. The field also does not default to auto, 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.

$ 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.

Retrying Failed Porting Attempts

The completePorting intent can also be called for previously failed porting requests. This enables users to resolve the issues themselves by addressing specific errors without having to contact customer support.

This feature applies to porting requests that failed due to the following declinedCodes:

• portingAccountNumberRequiredOrInvalid
• portingAccountPinRequiredOrInvalid
• portingAddressRequiredOrInvalid
• portingPhoneNumberPortProtected

If a Connect Session is created with a non-applicable declinedCode, Connect will immediately redirect the user back to the callbackUrl with the bad_configuration status code. If no callbackUrl is provided, Connect will display an error screen.

Note: This functionality is optional and must be enabled. Contact your CS representative to activate this feature for your project.

Aborting the Porting Flow

Users have the option to abort the porting flow if they choose not to proceed further. When this happens:

• The callbackUrl provided during the Connect Session creation will be invoked.
• The status sent to the callbackUrl will be user_aborted.

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.

$ 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.

$ 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.

$ 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.

$ 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.

$ 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.

$ 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.

$ 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.

$ 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