# About Connect Sessions
## Prerequisites
In order to use Connect Sessions, you will need:
- A valid API key ([learn how to create one][create-api-key])
- A project with Connect enabled (reach out to [support@gigs.com][gigs-support] for assistance)
## What Connect Sessions are
Connect Sessions allow developers to streamline the user experience by launching Connect in the state it needs to be in for the user to perform a certain action, eliminating unnecessary steps. This is achieved by specifying an _intent_ when creating the Connect Session.
An _intent_ could be purchasing a subscription or updating a users' payment method (for a full list of possible intents, please refer to the [API documentation][create-connect-session] or the dedicated sections about intents in this guide).
Not all intents are compatible with all projects. Most intents require the [Payments API](/payments) and are not available for projects using the [Billing API](/billing). See the [intent reference below](#available-intents) for details on which intents are compatible with your project's configuration.
You can make using Connect smoother for users by automatically filling in data you already have when setting up the Connect Session. This way, users don't have to input information you already have again. For instance, if you're aware of the user's chosen plan and their details, add this information when you create the Connect Session. As a result, users can go straight to the checkout without having to log in again, type in their details a second time, or select a plan.
## How Connect Sessions are created
```mermaid
sequenceDiagram
participant C as Your Application
participant GA as Gigs API
participant GC as Gigs Connect
C->>GA: Create Connect Session
activate GA
GA->>C: Return Connect session
deactivate GA
C->>GC: Redirect user to url from Connect session
activate GC
GC->>GC: User performs intended actions
GC->>C: User returns to your application
deactivate GC
```
The flow is initiated by your application making a `POST` request to `/connectSessions`. The Gigs backend creates the Connect Session and returns it to you.
Within the Connect Session, you will find a `url` field that you can use to redirect the user from your application to Connect.
Connect verifies the Connect Session and redirects the user to the desired location (i.e. the checkout with a plan and SIM already selected). In the case of errors, Connect will redirect the user back to a `callbackUrl` you defined.
For more information on creating Connect Sessions, please refer to the [dedicated section of this guide][create-connect-sessions].
## Redirecting the user back to your application
If you have defined a `callbackUrl` in the Connect Session, then the user will be redirected to it whenever they have performed the intended action within Connect.
Please refer to the [dedicated section of this guide][link-back] for further information.
## Available intents
### Purchasing & checkout
| Intent | Use case |
| ------ | -------- |
| [checkoutNewSubscription][intent-checkoutnewsubscription] | How do I let a user purchase a new plan? |
| [checkoutAddon][intent-checkoutaddon] | How do I let a user buy an add-on for their subscription? |
| Intent | Use case | Billing | Payments |
| ------ | -------- | :-----: | :------: |
| [checkoutNewSubscription][intent-checkoutnewsubscription] | How do I let a user purchase a new plan? | No | Yes |
| [checkoutAddon][intent-checkoutaddon] | How do I let a user buy an add-on for their subscription? | No | Yes |
### Subscription management
| Intent | Use case |
| ------ | -------- |
| [viewSubscriptions][intent-viewsubscriptions] | How do I show a user all their subscriptions? |
| [viewSubscription][intent-viewsubscription] | How do I show a user details of a specific subscription? |
| [changeSubscription][intent-changesubscription] | How do I let a user upgrade or change their plan? |
| [cancelSubscription][intent-cancelsubscription] | How do I let a user cancel their subscription? |
| [resumeSubscription][intent-resumesubscription] | How do I let a user resume a cancelled subscription? |
| Intent | Use case | Billing | Payments |
| ------ | -------- | :-----: | :------: |
| [viewSubscriptions][intent-viewsubscriptions] | How do I show a user all their subscriptions? | No | Yes |
| [viewSubscription][intent-viewsubscription] | How do I show a user details of a specific subscription? | No | Yes |
| [changeSubscription][intent-changesubscription] | How do I let a user upgrade or change their plan? | No | Yes |
| [cancelSubscription][intent-cancelsubscription] | How do I let a user cancel their subscription? | No | Yes |
| [resumeSubscription][intent-resumesubscription] | How do I let a user resume a cancelled subscription? | No | Yes |
### Payment management
| Intent | Use case |
| ------ | -------- |
| [confirmPayment][intent-confirmpayment] | How do I let a user confirm a pending payment? |
| [updatePaymentMethod][intent-updatepaymentmethod] | How do I let a user update their payment method? |
| Intent | Use case | Billing | Payments |
| ------ | -------- | :-----: | :------: |
| [confirmPayment][intent-confirmpayment] | How do I let a user confirm a pending payment? | No | Yes |
| [updatePaymentMethod][intent-updatepaymentmethod] | How do I let a user update their payment method? | No | Yes |
### Porting & eSIM
| Intent | Use case |
| ------ | -------- |
| [completePorting][intent-completeporting] | How do I let a user complete number porting? |
| [viewEsimInstallation][intent-viewesiminstallation] | How do I show a user their eSIM installation instructions? |
| Intent | Use case | Billing | Payments |
| ------ | -------- | :-----: | :------: |
| [completePorting][intent-completeporting] | How do I let a user complete number porting? | Yes | Yes |
| [viewEsimInstallation][intent-viewesiminstallation] | How do I show a user their eSIM installation instructions? | Yes | Yes |
### User profile
| Intent | Use case |
| ------ | -------- |
| [updateUserAddress][intent-updateuseraddress] | How do I let a user update their address? |
| [updateUserFullName][intent-updateuserfullname] | How do I let a user update their name? |
| Intent | Use case | Billing | Payments |
| ------ | -------- | :-----: | :------: |
| [updateUserAddress][intent-updateuseraddress] | How do I let a user update their address? | No | Yes |
| [updateUserFullName][intent-updateuserfullname] | How do I let a user update their name? | No | Yes |
## Where to go from here
- Read the [Connect Sessions API Documentation][create-connect-session]
- Read about [Creating Connect Sessions][create-connect-sessions]
- Reach out to [support@gigs.com][gigs-support] for assistance
[create-api-key]: /api/authentication
[gigs-support]: mailto:support@gigs.com
[create-connect-session]: /connect/connect-sessions#create-a-connect-session
[create-connect-sessions]: /docs/connect/connect-sessions/creating-connect-sessions
[link-back]: /docs/connect/connect-sessions/link-back
[intent-checkoutnewsubscription]: /docs/connect/connect-sessions/intent-checkoutnewsubscription
[intent-checkoutaddon]: /docs/connect/connect-sessions/intent-checkoutaddon
[intent-viewsubscriptions]: /docs/connect/connect-sessions/intent-viewsubscriptions
[intent-viewsubscription]: /docs/connect/connect-sessions/intent-viewsubscription
[intent-changesubscription]: /docs/connect/connect-sessions/intent-changesubscription
[intent-cancelsubscription]: /docs/connect/connect-sessions/intent-cancelsubscription
[intent-resumesubscription]: /docs/connect/connect-sessions/intent-resumesubscription
[intent-confirmpayment]: /docs/connect/connect-sessions/intent-confirmpayment
[intent-updatepaymentmethod]: /docs/connect/connect-sessions/intent-updatepaymentmethod
[intent-completeporting]: /docs/connect/connect-sessions/intent-completeporting
[intent-viewesiminstallation]: /docs/connect/connect-sessions/intent-viewesiminstallation
[intent-updateuseraddress]: /docs/connect/connect-sessions/intent-updateuseraddress
[intent-updateuserfullname]: /docs/connect/connect-sessions/intent-updateuserfullname