# Subscriptions

Source: https://developers.swell.is/frontend-api/subscriptions

**Swell.js:**

Manage subscriptions associated with the logged-in customer's [account](https://developers.swell.is/backend-api/accounts/the-account-model).

### List subscriptions

Return a list of active and canceled subscriptions for an account.

*Returns all subscriptions, with offset pagination using* *`limit`* *and* *`page`**.*

**List subscriptions**

**swell.js**

```javascript
await swell.subscriptions.list()
```

### Get a subscription

Return a single subscription by ID.

**Get a subscription**

**swell.js**

```javascript
await swell.subscriptions.get(id)
```

### Subscription management

Methods to create, update, and pause a subscription.

#### Create a new subscription

Subscribe the customer to a new product for recurring billing.

**Create a new subscription**

**swell.js**

```javascript
await swell.subscriptions.create({
  product_id: '5c15505200c7d14d851e510f',
  // the following parameters are optional
  variant_id: '5c15505200c7d14d851e510g',
  quantity: 1,
  coupon_code: '10PERCENTOFF',
  items: [
    {
      product_id: '5c15505200c7d14d851e510h',
      quantity: 1
    }
  ]
})
```

#### Update a subscription

Updates a single subscription.

**Update a subscription**

**swell.js** `Apply a coupon code`

```javascript
await swell.subscriptions.update('5c15505200c7d14d851e510f', {
  // the following parameters are optional
  quantity: 2,
  coupon_code: '10PERCENTOFF',
  items: [
    {
      product_id: '5c15505200c7d14d851e510h',
      quantity: 1
    }
  ]
})
```

**swell.js** `Change the quantity of the product`

```javascript
await swell.subscriptions.update('5c15505200c7d14d851e510f', {
  product_id: '5c15505200c7d14d851e510g',
  variant_id: '5c15505200c7d14d851e510h', // optional
  quantity: 2
})
```

#### Pause a subscription

Pauses a subscription indefinitely or skips a billing cycle.

**Pause a subscription**

**swell.js** `Immediately and indefinitely`

```javascript
await swell.subscriptions.update(subscription.id, {
  paused: true,
  date_pause_end: null
})
```

**swell.js** `Skip a subscription cycle`

```javascript
await swell.subscriptions.update(subscription.id, {
  paused: true,
  date_pause_end: "2023-01-15T00:00:00" // Date to resume subscription
})
```

#### Cancel a subscription

Cancel a single subscription.

**Cancel a subscription**

**swell.js**

```javascript
await swell.subscriptions.update('5c15505200c7d14d851e510f', {
  canceled: true
})
```

### Item management

Methods to add, update, and remove an invoice item on a subscription.

#### Add an invoice item

Returns the updated subscriptions object.

**Add an invoice item**

**swell.js**

```javascript
await swell.subscriptions.addItem('5c15505200c7d14d851e510f', {
  product_id: '5c15505200c7d14d851e510f',
  quantity: 1,
  options: [
    {
      id: 'color',
      value: 'Blue'
    }
  ]
})
```

#### Update one or all invoice items

Returns the updated subscriptions object.

**Update invoice item(s) on a subscription**

**swell.js** `Update one item`

```javascript
await swell.subscriptions.updateItem('5c15505200c7d14d851e510f', '<item_id>', {
  quantity: 2
})
```

**swell.js** `Update all items`

```javascript
await swell.subscriptions.setItems('5c15505200c7d14d851e510e', [
  {
    id: '5c15505200c7d14d851e510f',
    quantity: 2,
    options: [
      {
        id: 'color',
        value: 'Blue'
      }
    ]
  },
  {
    id: '5c15505200c7d14d851e510g',
    quantity: 3,
    options: [
      {
        id: 'color',
        value: 'Red'
      }
    ]
  },
  {
    id: '5c15505200c7d14d851e510h',
    quantity: 4,
    options: [
      {
        id: 'color',
        value: 'White'
      }
    ]
  }
])
```

#### Remove one or multiple items

Returns the updated subscriptions object.

**Remove invoice item(s) from a subscription**

**swell.js** `Remove one item`

```javascript
await swell.subscriptions.removeItem('5c15505200c7d14d851e510f', '<item_id>')
```

**swell.js** `Remove multiple items`

```javascript
await swell.subscriptions.setItems('5c15505200c7d14d851e510f', [])
```

**GraphQL:**

Manage subscriptions associated with the logged-in customer's [account](https://developers.swell.is/backend-api/accounts/the-account-model).

### List subscriptions

Return a list of active and canceled subscriptions for an account.

The parameters of this query are `search`, `where`, `sort`, `limit`, `page`, `_locale`, and `_currency`.

**List subscriptions**

**GraphQL**

```graphql
query getSubscriptions {
  subscriptions(_currency: "USD") {
    results {
      id
      status
      datePeriodEnd
      product {
        name
        id
        slug
        price
      }
      billingSchedule {
        interval
        intervalCount
        trialDays
      }
      recurringTotal
    }
  }
}
```

### Get a subscription

Return a single subscription by ID.

The parameters of this query are `id`, `_locale`, and `_currency`.

**Get a subscription**

**GraphQL**

```graphql
query getSubscriptionById {
  subscriptionById(id: "62b1e30767145000197b2bc0") {
    status
    datePeriodEnd
    quantity
    trial
    dateTrialEnd
    product {
      id
      name
      slug
      price
    }
    grandTotal
    currency
    shipping {
      name
      address1
      city
      state
      country
      zip
    }
    billing {
      name
      address1
      city
      state
      country
      zip
      method
      card {
        brand
        last4
        expMonth
        expYear
      }
    }
    billingSchedule {
      interval
      intervalCount
    }
  }
}
```

### Subscription management

Methods to create, update, and pause a subscription.

#### Create a new subscription

Subscribe the customer to a new product for recurring billing. Returns the updated subscription object.

The parameters of this mutation are `input` (required).

**Create a new subscription**

**GraphQL**

```graphql
mutation createSubscription {
  createSubscription(
    input: { productId: "62b1e30767145000197b2bbf", quantity: 1 }
  ) {
    product {
      name
      id
      price
    }
    quantity
    trial
    grandTotal
  }
}
```

#### Update a subscription

Updates a single subscription. Returns the updated subscription object.

The parameters of this mutation are `id` (required) and `input` (required).

**Update a subscription plan**

**GraphQL** `Change the quantity and apply a coupon`

```graphql
mutation updateSubscription {
  updateSubscription(
    id: "62b9ee09e744d10013710365"
    input: {
      productId: "62b1e30767145000197b2bbf"
      quantity: 2
      couponCode: "10PERCENTOFF"
    }
  ) {
    product {
      name
      id
      price
    }
    quantity
    trial
    grandTotal
  }
}
```

**GraphQL** `Replace the subscription product with another product`

```graphql
mutation replaceSubscriptionProduct {
  updateSubscription(
    id: "62b9ee09e744d10013710365"
    input: {
      productId: "62b1e30767145000197b2bbf"
      items: { productId: "64b1e30767145000197b2bbf", quantity: 1 }
    }
  ) {
    product {
      name
      id
      price
    }
    quantity
    trial
    grandTotal
  }
}
```

#### Pause a subscription

Pauses a subscription indefinitely or skips a billing cycle. Returns the updated subscription object.

The parameters of this mutation are `id` (required) and `input` (required).

**Pause a subscription**

**GraphQL** `Immediately and indefinitely`

```graphql
mutation pauseSubscription {
  updateSubscription(
    id: "62b9ee09e744d10013710365"
    input: { paused: true, datePauseEnd: null }
  ) {
    product {
      name
      id
      price
    }
    status
    quantity
    grandTotal
  }
}
```

**GraphQL** `Skip a subscription cycle`

```graphql
mutation skipSubscription {
  updateSubscription(
    id: "62b9ee09e744d10013710365"
    input: {
      paused: true
      datePauseEnd: "2023-01-15T00:00:00" # Date to resume subscription
    }
  ) {
    product {
      name
      id
      price
    }
    status
    quantity
    grandTotal
  }
}
```

#### Cancel a subscription

Cancel a single subscription. Returns the updated subscription object.

The parameters of this mutation are `id` (required) and `input` (required).

**Cancel a subscription**

**GraphQL**

```graphql
mutation cancelSubscription {
  updateSubscription(
    id: "62b9ee09e744d10013710365"
    input: { productId: "62b1e30767145000197b2bbf", canceled: true }
  ) {
    product {
      name
      id
      price
    }
    status
    quantity
    grandTotal
  }
}
```

### Invoice management

Methods to add, update, and remove an invoice item on a subscription.

#### Add an invoice item

Add an invoice item to a subscription. Returns the updated subscription object.

The parameters of this mutation are `subscriptionId` (required) and `input` (required).

**Add an invoice item**

**GraphQL**

```graphql
mutation addSubscriptionItem {
  addSubscriptionItem(
    subscriptionId: "62b9f39d8b9a9a00133b7784"
    input: { productId: "62b1e30767145000197b2bbf", quantity: 1 }
  ) {
    product {
      name
      id
      price
    }
    quantity
    priceTotal
  }
}
```

#### Update an item

Update an invoice item on a subscription. Returns the updated subscription object.

The parameters of this mutation are `subscriptionId` (required), `itemId` (required), and `input` (required).

**Update an invoice item on a subscription**

**GraphQL**

```graphql
mutation updateSubscriptionItem {
  updateSubscriptionItem(
    subscriptionId: "62b9f39d8b9a9a00133b7784"
    itemId: "62b9f12391fed80013478224"
    input: { quantity: 2 }
  ) {
    product {
      name
      id
      price
    }
    quantity
    grandTotal
  }
}
```

#### Remove an item

Remove an item from a subscription. Returns the updated subscription object.

The parameters of this mutation are `subscriptionId` (required) and `itemId` (required).

**Remove an invoice item from a subscription**

**GraphQL**

```graphql
mutation deleteSubscriptionItem {
  deleteSubscriptionItem(
    subscriptionId: "62b9f39d8b9a9a00133b7784"
    itemId: "62b9f12391fed80013478224"
  ) {
    product {
      name
      id
      price
    }
    quantity
    priceTotal
  }
}
```