---
title: useSubscription
slug: oms/usesubscription
docTags: 
createdAt: 2022-11-07T21:27:00.000Z
---

:::hint{type="info"}
**This page's documentation only applies to Chord's** [Next.js starter](https://github.com/chordcommerce/nextjs-starter-autonomy) **prior to the release of the **[React](docId\:EwXkRz0JhH0zPphIkkcrI)**. The Next.js starter now uses the React SDK and does not use the methods documented on this page. Check out the** [React SDK Reference](https://docs-beta.chord.co/chord-ui/module-react-autonomy) **for complete documentation, and the **[React SDK Migration Guide](docId\:qMilHJFPz9WbJYZbe50Ku)**for details on how to upgrade.**
:::

The `useSubscription` hook returns the current loaded subscription and functions for managing the subscription.

## Example

```javascript
import { useSubscription } from '~/hooks/actions'

export default () => {  
  const { subscription } = useSubscription()
  
  return (    
    <p>Your subscription will be renewed on {subscription.actionableDate}</p>  
  )
}
```

```javascript
import { useSubscription } from '~/hooks/actions'

// inside a function component
const { subscripion, loadSubscription } = useSubscription()
```

## Returns

The `useSubscription` hook returns an object with these properties:

| Property             | Description                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `subscription`       | An object representing a subscription. You will need to explicitly call `loadSubscription` before this object will be populated. |
| `loadSubscription`   | A function that loads the subscription.                                                                                          |
| `skipSubscription`   | A function that skips the next subscription delivery.                                                                            |
| `cancelSubscription` | A function that cancels the subscription.                                                                                        |
| `pauseSubscription`  | A function that pauses the subscription.                                                                                         |
| `resumeSubscription` | A function that resumes the subscription.                                                                                        |
| `updateSubscription` | A function that updates the subscription.                                                                                        |

## Functions

### loadSubscription&#x20;

The `loadSubscription` function loads information about the subscription from the Chord API.

**Arguments:**

`loadSubscription(subscriptionId)`

| Argument         | Type   | Description                           |
| ---------------- | ------ | ------------------------------------- |
| `subscriptionId` | Number | The `id` of the subscription to load. |

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default subscriptionId => {  
  const { subscription, loadSubscription } = useSubscription()
  
  useEffect(() => {    
    loadSubscription(subscriptionId)  
  }, [])
  
  return (    
    <p>Your subscription will be renewed on {subscription.actionableDate}</p>
  )
}
```

### skipSubscription&#x20;

The `skipSubscription` function calls the Chord API to skip the next subscription delivery.

**Arguments:**

None.

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default subscriptionId => {  
  const { subscription, skipSubscription } = useSubscription()
  
  useEffect(() => {    
    skipSubscription()
  }, [])
  
  return (    
    <p>Your subscription will be renewed on {subscription.actionableDate}</p>  
  )
}
```

### cancelSubscription&#x20;

The `cancelSubscription` function calls the Chord API to cancel a subscription.

**Arguments:**

None.

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default subscriptionId => {  
  const { subscription, cancelSubscription } = useSubscription()
  
  useEffect(() => {    
    cancelSubscription()  
  }, [])
  
  return <p>Your subscription was canceled</p>
}
```

### pauseSubscription&#x20;

The`pauseSubscription` function calls the Chord API to pause a subscription.

Paused subscriptions will not be processed until manually`resumed`or the`actionableDate`is reached.

**Arguments:**

`pauseSubscription(options)`

| Argument                   | Type   | Description                                                                                                                                                                                 |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options?.actionableDate?` | String | (Optional): A date string representing when the subscription should resume. The minimum date is the next day. If `actionableDate` is omitted, the subscription will be paused indefinitely. |

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default () => {  
  const { pauseSubscription } = useSubscription(subscription.id)  
  const onSubmit = async data => {
    try {
      let response = await pauseSubscription({
        'actionableDate': '2030-08-18'
      })
      console.log(response)
    } catch (error) {
      console.error(error) 
    }
  }
}
```

### resumeSubscription&#x20;

The`resumeSubscription`function calls the Chord API to resume a subscription.

Paused subscriptions will not be processed until manually`resumed`or the`actionableDate`is reached.

**Arguments:**

`resumeSubscription(options)`

| Argument                   | Type   | Description                                                                                                                                                                                  |
| -------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options?.actionableDate?` | String | (Optional): A date string representing when the subscription should resume. The minimum date is the next day. If `actionableDate` is omitted, the subscription will be resumed the next day. |

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default () => {  
  const { resumeSubscription } = useSubscription(subscription.id)  
  const onSubmit = async data => {
    try {
      let response = await resumeSubscription({
        'actionableDate': '2030-08-18'
      })
      console.log(response)
    } catch (error) {
      console.error(error) 
    }
  }
}
```

### updateSubscription&#x20;

The`updateSubscription` function calls the Chord API to update a subscription.

**Arguments:**

`updateSubscription(options)`

| Argument                         | Type                                   | Description                                                                                                                                                                                  |
| -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options.actionableDate?`        | String                                 | (Optional): A date string representing when the subscription should resume. The minimum date is the next day. If `actionableDate` is omitted, the subscription will be resumed the next day. |
| `options.billAddressAttributes?` | Object                                 | (Optional) An object representing the billing address. All fields need to be sent even if only a single field is updated.                                                                    |
| `options.endDate?`               | String \| Null                         | (Optional) A string representing the end date of the subscription. If `null`, the subscription will renew indefinitely.                                                                      |
| `options.shipAddressAttributes?` | Object                                 | (Optional) An object representing the shipping address. All fields need to be sent even if only a single field is updated.                                                                   |
| `options.intervalLength?`        | Number                                 | (Optional): The number of units. *Example:* if the subscription should be delivered every three months, this would be `3`.                                                                   |
| `options.intervalUnit?`          | `"day" \| "week" \| "month" \| "year"` | (Optional): The interval unit. *Example:* if the subscription should be delivered every three months, this would be `month`.                                                                 |

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default () => {  
  const { updateSubscription } = useSubscription(subscription.id)  
  const onSubmit = async data => {
    try {
      let response = await updateSubscription({
        'shipAddressAttributes': data.addressAttributes,
        'billAddressAttributes': data.addressAttributes,
        'intervalUnits': 'month',
        'intervalLength': 2, 
        'endDate': '2021/12/31',
        'actionableDate': '2030-08-18'
      })
      console.log(response)
    } catch (error) {
      console.error(error) 
    }
  }
}

/*
  Default Form Values:
  
  const address = subscription['shipAddress']
  const addressAttributes = {
    name: address.name,
    address1: address.address1,
    address2: address.address2,
    city: address.city,
    state_name: address.state.abbr,
    country_iso: address.country.iso,
    zipcode: address.zipcode
  }
*/
```